Cloud Database Management
In this guide, you'll learn how to manage database instances in DBOS Cloud.
Provisioning Database Instances
Before you can deploy an application to DBOS Cloud, you must provision a Postgres database instance for it. You must choose a database instance name, username and password. Both the database instance name and username must be 3 to 16 characters long and contain only lowercase letters, numbers and underscores. The database password must contain 8 or more characters. Run this command and choose your database password when prompted:
npx dbos-cloud db provision <database-instance-name> -U <database-username>
A Postgres database instance can host multiple independent databases for different applications.
You can configure which database your application uses through the app_db_name field in its dbos-config.yaml.
If you forget your database password, you can always reset it.
To see a list of all provisioned instances, run:
npx dbos-cloud db list
To retrieve the status of a particular instance, run:
npx dbos-cloud db status <database-instance-name>
Database Schema Management
To manage your applications' database schemas, you must define schema migrations. DBOS Cloud is compatible with any schema management tool as long as all its dependencies and assets are stored in your application directory. We recommend using a Typescript-based migration tool like Knex or TypeORM.
You configure your schema migrations in the migrate and rollback fields of your dbos-config.yaml.
You must supply a list of commands to run to migrate to your most recent schema version.
For example, if you are using Knex, you might use:
database:
# Other fields omitted
migrate: ['npx knex migrate:latest']
rollback: ['npx knex migrate:down']
To run your migrations locally, run npx dbos migrate or npx dbos rollback.
When you deploy an application to DBOS Cloud it runs npx dbos migrate to apply all schema changes before starting your application or updating its code.
When you roll back an application on DBOS Cloud, it runs npx dbos rollback to roll back schema changes before updating your application's code.
Be careful making breaking schema changes such as deleting or renaming a column—they may break active workflows running on a previous application version.
Database Recovery
DBOS Cloud can use PostgreSQL point-in-time-recovery to restore your database to a previous state, for example to recover from data corruption or loss.
First, run the database restore to create a new database instance containing the state of your database instance at a previous point in time:
npx dbos-cloud db restore <database-name> -t <timestamp> -n <new-db-instance-name>
The timestamp must be in RFC3339 format and must be within the backup retention period of your database (24 hours for free-tier users).
After the database is restored, you can redeploy your applications to it with app change-database-instance.
For each application connected to the original database instance, run:
npx dbos-cloud app change-database-instance --database <new-db-instance-name>
If you wish to restore your application to a previous version (such as the version that was running at the recovery timestamp), you can do this with the --previous-version parameter:
npx dbos-cloud app change-database-instance --database <new-db-instance-name> --previous-version <version-id>
For more information on application version management, see here.
Finally, destroy the original database instance:
npx dbos-cloud db destroy <original-database-instance-name>
Destroying Database Instances
To destroy a database instance, run:
npx dbos-cloud db destroy <database-name>
Take care—this will irreversibly delete all data in the database instance.