merge

docs/api-reference/cli.md

@@ -28,10 +28,26 @@ Parameters set from the command line take precedence over parameters set in the
 ### `npx dbos-sdk init`
 
 **Description:**  
-This command initializes a new DBOS application from a template into a target directory. By default, it sets the "Hello, Database!" application used in the [quickstart](../getting-started/quickstart).
+This command initializes a new DBOS application from a template into a target directory. By default, it instantiates the "Hello, Database!" application used in the [quickstart](../getting-started/quickstart).
 
 **Parameters:**  
-- `-n, --appName <application-name>`: The name and directory to which to initialize the application.
+- `-n, --appName <application-name>`: The name and directory to which to instantiate the application. Must not contain spaces or special characters.
+
+---
+
+### `npx dbos-sdk migrate`
+
+**Description:**
+Run all migration commands specified in your [configuration file](./configuration) to apply your application's schema to the database.
+
+---
+
+### `npx dbos-sdk rollback`
+
+**Description:**
+Run all rollback commands specified in your [configuration file](./configuration) to roll back the last batch of schema migrations.
+
+---
 
 ### `npx dbos-openapi generate`
 

docs/api-reference/cloud-cli.md

@@ -0,0 +1,176 @@
+---
+sidebar_position: 1
+title: Cloud CLI
+description: DBOS Cloud CLI reference
+---
+
+The DBOS Cloud CLI helps you serverlessly run your applications on DBOS Cloud
+
+## User Management Commands
+
+### `npx dbos-cloud register`
+
+**Description:**  
+This command creates and registers a new DBOS Cloud account.
+It provides a URL to a secure login portal from which you can create an account from your browser.
+
+**Parameters:**  
+- `-u, --username <string>`: Your DBOS Cloud username.
+
+---
+
+### `npx dbos-cloud login`
+
+**Description:**  
+This command logs you in to your DBOS Cloud account.
+It provides a URL to a secure login portal from which you can log in to your account from your browser.
+
+**Parameters:**  
+- `-u, --username <string>`: Your DBOS Cloud username.
+
+---
+
+### `npx dbos-cloud logout`
+
+**Description:**  
+This command logs you out of your DBOS Cloud account.
+
+---
+
+## Database Instance Management Commands
+
+### `npx dbos-cloud database provision <database-instance-name>`
+
+**Description:**  
+This command provisions a Postgres database instance to which your applications can connect.
+
+**Parameters:**  
+- `<database-instance-name>`: The name of the database instance to provision.
+- `-a, --admin <string>`: The administrator username for this database instance.
+- `-W, --password <string>`: The administrator password for this database instance.
+
+---
+
+### `npx dbos-cloud database list`
+
+**Description:**  
+This command lists all Postgres database instances provisioned by your account.
+
+**Parameters:**  
+- `--json`: Emit JSON output
+
+**Output:**
+For each provisioned Postgres database instance, emit:
+- `PostgresInstanceName`: The name of this database instance.
+- `HostName`: The hostname of this database instance.
+- `Port`: The connection port for this database instance.
+- `Status`: The current status of this database instance (available or unavailable).
+- `AdminUsername`: The administrator username for this database instance.
+
+---
+
+### `npx dbos-cloud database status <database-instance-name>`
+
+**Description:**  
+This command retrieves the status of a Postgres database instance
+
+**Parameters:**  
+- `<database-instance-name>`: The name of the database instance whose status to retrieve.
+- `--json`: Emit JSON output
+
+**Output:**
+- `PostgresInstanceName`: The name of the database instance.
+- `HostName`: The hostname of the database instance.
+- `Port`: The connection port for the database instance.
+- `Status`: The current status of the database instance (available or unavailable).
+- `AdminUsername`: The administrator username for the database instance.
+
+---
+
+### `npx dbos-cloud database destroy <database-instance-name>`
+
+**Description:**  
+This command destroys a previously-provisioned Postgres database instance.
+
+**Parameters:**  
+- `<database-instance-name>`: The name of the database instance whose status to retrieve.
+
+---
+
+## Application Management Commands
+
+### `npx dbos-cloud application register`
+
+**Description:**  
+This command must be run from an application root directory.
+It registers that application with DBOS Cloud.
+
+**Parameters:**  
+- `-d, --database <string>`: The name of the Postgres database instance to which this application will connect.
+
+---
+
+### `npx dbos-cloud application deploy`
+
+**Description:**  
+This command must be run from an application root directory.
+It deploys the application to DBOS Cloud and emits the URL at which the application is hosted, which is `https://cloud.dbos.dev/apps/<username>/<application-name>`.
+By default, it builds the application using Docker before deployment to guarantee compatibility with our cloud environment.
+
+**Parameters:**  
+- `--no-docker`: Do not build the application with Docker. If using this option, you must install dependencies and build your application locally before deploying.
+
+---
+
+### `npx dbos-cloud application delete`
+
+**Description:**  
+This command must be run from an application root directory.
+It deletes the application from DBOS Cloud.
+
+---
+
+### `npx dbos-cloud application list`
+
+**Description:**  
+List all applications you have registered with DBOS Cloud.
+
+**Parameters:**  
+- `--json`: Emit JSON output
+
+**Output:**
+For each registered application, emit:
+- `Name`: The name of this application
+- `ID`: The unique ID DBOS Cloud assigns to this application.
+- `PostgresInstanceName`: The Postgres database instance to which this application is connected.
+- `ApplicationDatabaseName`: The database on this instance on which this application stores data.
+- `Status`: The current status of this application (available or unavailable).
+- `Version`: The currently deployed version of this application.
+---
+
+### `npx dbos-cloud application status`
+
+**Description:**  
+This command must be run from an application root directory.
+It retrieves that application's status.
+
+**Parameters:**  
+- `--json`: Emit JSON output
+
+**Output:**
+- `Name`: The name of this application
+- `ID`: The unique ID DBOS Cloud assigns to this application.
+- `PostgresInstanceName`: The Postgres database instance to which this application is connected.
+- `ApplicationDatabaseName`: The database on this instance on which this application stores data.
+- `Status`: The current status of this application (available or unavailable).
+- `Version`: The currently deployed version of this application.
+---
+
+### `npx dbos-cloud application logs`
+
+**Description:**  
+This command must be run from an application root directory.
+It retrieves that application's logs.
+
+**Parameters:**  
+- `-l, --last <integer>`: How far back to query, in seconds from current time. By default, retrieve all data.

docs/api-reference/configuration.md

@@ -27,11 +27,12 @@ DBOS currently only supports Postgres-compatible databases.
 - **port**: Database port.
 - **username**: Username with which to connect to the database.
 - **password**: Password with which to connect to the database.  We strongly recommend using an environment variable for this field, instead of plain text.
-- **user_database**: Name of the application database.
-- **system_database** (optional): Name of a database to which DBOS can write system data.  Defaults to `dbos_systemdb`.
-- **ssl_ca** (optional): If using SSL/TLS to securely connect to a database, path to an SSL root certificate file.  Equivalent to the [`sslrootcert`](https://www.postgresql.org/docs/current/libpq-ssl.html) connection parameter in `psql`.  Defaults to not using SSL.
+- **app_db_name**: Name of the application database.
+- **app_db_client** (optional): Client to use for connecting to the application database. Must be either `knex` or `typeorm`.  Defaults to `knex`.  The client specified here is the one used in [`TransactionContext`](../api-reference/contexts#transactioncontextt).
+- **ssl_ca** (optional): If using SSL/TLS to securely connect to a database, path to an SSL root certificate file.  Equivalent to the [`sslrootcert`](https://www.postgresql.org/docs/current/libpq-ssl.html) connection parameter in `psql`.
 - **connectionTimeoutMillis** (optional): Database connection timeout in milliseconds. Defaults to `3000`.
-- **user_dbclient** (optional): Client to use for connecting to the application database. Must be one of `knex`, `prisma`, or `typeorm`.  Defaults to `knex`.  The client specified here is the one used in [`TransactionContext`](../api-reference/contexts#transactioncontextt).
+- **migrate** (optional): A list of commands to run to apply your application's schema to the database. We recommend using a migration tool like those built into [Knex](https://knexjs.org/guide/migrations.html) and [TypeORM](https://typeorm.io/migrations).
+- **rollback** (optional) A list of commands to run to roll back the last batch of schema migrations.
 
 **Example**:
 
@@ -41,9 +42,10 @@ database:
   port: 5432
   username: 'postgres'
   password: ${PGPASSWORD}
-  user_database: 'hello'
-  system_database: 'hello_systemdb' # Optional, defaults to 'dbos_systemdb'
-  user_dbclient: 'knex' # knex (default) | prisma | typeorm
+  app_db_name: 'hello'
+  app_db_client: 'knex'
+  migrate: ['npx knex migrate:latest']
+  rollback: ['npx knex migrate:rollback']
 ```
 
 ---

docs/api-reference/contexts.md

@@ -311,7 +311,7 @@ Transactions use `TransactionContext` to interact with the database.
 ### Generic Type Parameter
 
 `TransactionContext` is typed generically based on the application database client in use.
-The application database client is configurable in a project's [configuration file](./configuration) (`user_dbclient`).
+The application database client is configurable in a project's [configuration file](./configuration) (`app_db_client`).
 DBOS currently supports the following clients:
 
 **[Knex](https://knexjs.org/guide/#typescript)**
@@ -328,21 +328,14 @@ import { EntityManager } from "typeorm";
 static async exampleTransaction(ctxt: TransactionContext<EntityManager>, ...)
 ```
 
-**[Prisma](https://www.prisma.io/docs/concepts/components/prisma-client)**
-
-```typescript
-import { PrismaClient } from "@prisma/client";
-static async exampleTransaction(ctxt: TransactionContext<Prisma>, ...)
-```
-
 ### Properties
 
 - [client](#transactionctxtclient)
 
 ### transactionCtxt.client
 
 ```typescript
-client: T; // One of [Knex, EntityManager, PrismaClient]
+client: T; // One of [Knex, EntityManager]
 ```
 
 Provides access to the chosen application database client.
@@ -504,18 +497,15 @@ The `query` fucntion provides read access to the database.  See [Placing Databas
 
 ### Placing Database Queries From `MiddlewareContext`
 
-`MiddlewareContext` supports read-only database queries, via a method called `query`.  To provide a scoped database connection and to ensure cleanup, the `query` API works via a callback function.  The application is to pass in a `qry` function that will be executed in a context with access to the database client `dbclient`.  The provided `dbClient` will either be a `Knex`, `PrismaClient`, or TypeORM `EntityManager` depending on the application's choice of SQL access library.  This callback function may take arguments, and return a value.
+`MiddlewareContext` supports read-only database queries, via a method called `query`.  To provide a scoped database connection and to ensure cleanup, the `query` API works via a callback function.  The application is to pass in a `qry` function that will be executed in a context with access to the database client `dbclient`.  The provided `dbClient` will either be a `Knex` or TypeORM `EntityManager` depending on the application's choice of SQL access library.  This callback function may take arguments, and return a value.
 
-Example, for Prisma:
+Example, for Knex:
 ```typescript
   const u = await ctx.query(
-    (dbClient: PrismaClient, uname: string) => {
-      return dbClient.dbos_test_user.findFirst({
-        where: {
-          username: uname,
-        },
-      });
+    // The qry function that takes in a dbClient and a list of arguments (uname in this case)
+    (dbClient: Knex, uname: string) => {
+      return dbClient<UserTable>(userTableName).select("username").where({ username: uname })
     },
-    user
+    userName // Input value for the uname argument
   );
 ```

docs/api-reference/testing-runtime.md

@@ -14,7 +14,7 @@ After your tests finish, [destroy the runtime](#runtimedestroy) to release resou
 ::::tip
 
 If you use TypeORM, you can use the testing runtime to [create](#runtimecreateuserschema) or [drop](#runtimedropuserschema) your schemas.
-If you use Knex or Prisma, you are responsible for setting up schemas/tables and cleaning them up.
+If you use Knex, you are responsible for setting up schemas/tables and cleaning them up, for example by using Knex migrations.
 
 ::::
 

docs/getting-started/quickstart.md

@@ -8,10 +8,10 @@ import TabItem from '@theme/TabItem';
 
 # DBOS SDK Quickstart
 
-Here's how to get a simple "hello world" DBOS application up and running in less than five minutes!
+Here's how to get a simple DBOS "Hello, Database!" application up and running in less than five minutes!
 
 ### System Requirements
-The DBOS SDK requires [Node.js 20 or later](https://nodejs.org/en).  To install (assuming you don't already have Node.js installed), run the following commands in your terminal:
+The DBOS SDK requires [Node.js 20 or later](https://nodejs.org/en).  To install (assuming you don't already have Node.js installed), copy and run the following commands in your terminal:
 
 <Tabs groupId="operating-systems">
   <TabItem value="mac" label="macOS">

docs/tutorials/demo-apps.md

@@ -4,7 +4,7 @@ title: Demo Applications
 description: Learn how to build larger apps with DBOS
 ---
 
-To show you how to develop larger applications with DBOS, we've built three demo applications, each highlighting a different set of DBOS's powerful features.
+To show you how to develop larger applications with DBOS, we've built two demo applications, each highlighting a different set of DBOS's powerful features.
 
 ## [E-Commerce](https://github.com/dbos-inc/dbos-demo-apps/tree/main/e-commerce)
 
@@ -19,20 +19,6 @@ The E-Commerce demo demonstrates:
 
 For more technical details, please see the [Under the Covers](https://github.com/dbos-inc/dbos-demo-apps/blob/main/e-commerce/README.md#under-the-covers) section of the E-Commerce README.
 
-## [Bank](https://github.com/dbos-inc/dbos-demo-apps/tree/main/bank)
-
-The Bank demo is a toy banking app. Users can deposit or withdraw "cash" or transfer money between accounts potentially in different banks.
-
-The Bank demo demonstrates:
-* Reliable orchestration of complex workflows involving multiple database transactions and communicators
-* Using [Prisma](https://www.prisma.io/) for database interaction and schema management
-* Setting an [idempotency key](./idempotency-tutorial.md) in HTTP header for exactly-once cross-bank transactions
-* JWT-based authentication through integration with an external [Keycloak](https://www.keycloak.org/) service
-* [Declarative security](./authentication-authorization.md)
-* Unit tests with the [testing runtime](./testing-tutorial.md)
-* Integration with an [Angular](https://angular.io/) frontend
-
-
 ## [YKY Social](https://github.com/dbos-inc/dbos-demo-apps/tree/main/yky-social)
 YKY Social is a toy social network app, which allows users to register, create profiles, follow friends, and post messages to each other.
 

docs/tutorials/transaction-tutorial.md

@@ -20,7 +20,7 @@ As with other DBOS functions, inputs and outputs must be serializable to JSON.
 The [`TransactionContext`](../api-reference/contexts#transactioncontextt) provides a `.client` field you can use to transactionally interact with the database, so you don't need to worry about managing database connections.
 By default, this is a [Knex.js](https://knexjs.org/) client.
 We like Knex because it's lightweight and helps us write fast and type-safe queries.
-However, if you prefer a traditional ORM, we also support [Prisma](./using-prisma.md) and [TypeORM](./using-typeorm.md).
+However, if you prefer a traditional ORM, we also support [TypeORM](./using-typeorm.md).
 
 Here's an example of a transaction function (from the [quickstart](../getting-started/quickstart)) written using raw SQL (calling it with [knex.raw](https://knexjs.org/guide/raw.html)):