Docs menu

Deploy and run

Databases

Create Postgres, MySQL, Redis or MongoDB, connect it to your app, and keep its data safe with backups, branches and standbys.

Explain it

CLI runs private databases (Postgres, MySQL, Redis and MongoDB) next to your apps. Each is backed up every day, only your project's apps can reach it, and connecting an app takes one click.

How to do it: in a project, press Add and choose a database, then Connect it to your app: CLI sets the connection variable for you. Open the database to browse tables, run queries, restore a backup, or make a safe copy with personal data scrubbed.

"Add Postgres to my project and connect it to the web app."

Before changing your database's structure, see Safe database migrations: CLI checks a change for anything that loses data.

CLI runs private databases next to your apps. Each one gets generated credentials and a persistent volume, is reachable only from apps in the same project, and is backed up every day. It's billed like any other service, by the minute for the size you choose.

Create a database

You can create Postgres, MySQL, Redis or MongoDB.

In the dashboard: choose New service, then Database. Pick an engine, give it a name and press Create Postgres (or whichever engine you picked).

From your terminal:

Terminal
cli add postgres
cli db create redis --name cache --link

cli add creates the database and connects it to the linked service in one step. cli db create creates it, and --link connects it.

Ask your agent:

"Add a Postgres database called postgres and connect it to web."

With the API:

API
POST /v1/projects/:id/databases
JSON
{ "kind": "postgres", "name": "postgres", "linkTo": "svc_web123" }

kind is postgres, mysql, redis or mongo. linkTo is optional.

Connect it to an app

Connecting a database stores its URL in the app as a secret variable: DATABASE_URL for Postgres, MYSQL_URL, REDIS_URL or MONGO_URL for the others. You can pick another name. Then redeploy the app so it sees the variable.

In the dashboard: open the app, go to Variables and use Connect a database. Or pick the database's URL from the reference list.

From your terminal:

Terminal
cli db link postgres
cli db link cache --var CACHE_URL
cli deploy

With the API:

API
POST /v1/services/:appId/link
JSON
{ "databaseId": "svc_pg456", "var": "DATABASE_URL" }

You can also write a reference yourself, ${{postgres.DATABASE_URL}}, so the app always gets the current URL. See Variables and configuration.

Connection details

In the dashboard: the database's Connect tab shows its private and public URLs.

From your terminal:

Terminal
cli db connect postgres
cli db connect postgres --public

--public opens a port for your machine only. See Domains and networking for public database ports.

Seeing a URL with its password needs the developer role or higher (and the secrets scope for keys), and every read is logged. Credentials can't be edited, but they can be rotated: see Buckets, queues and secrets.

Query from the dashboard

For Postgres and MySQL, the Data tab lists tables with row counts and lets you run SQL. Queries are read-only unless you're an admin and choose to write.

From your terminal:

Terminal
cli db tables postgres
cli db query postgres "select id, email from users limit 10"

Add --write to run a query that changes data.

Schema, saved queries and migrations

Under the data viewer, on the Data tab:

  • Schema: every table with its columns, types, which are required, and the primary key (GET /v1/services/:id/schema).
  • Saved queries: queries the whole team can open again (POST /v1/services/:id/saved-queries).
  • Run a migration: give it a name and the SQL, and choose Back up and run. CLI takes a fresh backup first. If that fails, nothing runs. Then it runs the SQL in one transaction: on Postgres it's all or nothing, and a failed migration changes nothing. MySQL commits schema changes one at a time, so a failure there can leave part of it applied. Restore the backup taken just before if you need to go back. Every run is kept in the history with its backup.
API
POST /v1/services/:id/migrations {"name": "add phone to users", "sql": "ALTER TABLE users ADD COLUMN phone text;"}

Migrations change data, so they're for admins, need a recent second sign-in like write queries, and an agent's needs a person's approval. Agents use cli_db_tools.

Backups and restore

Every running database is backed up daily. Backups are encrypted and kept for 7 days. Stored backups are billed per GB-month, by the hour.

In the dashboard: the database's Backups tab lists backups, and has buttons to back up now and to restore.

From your terminal:

Terminal
cli db backups postgres
cli db backup postgres
cli db restore bak_abc123

With the API:

API
POST /v1/services/:id/backups
POST /v1/backups/:id/restore
JSON
{ "confirm": "postgres" }

A restore replaces all the data in the database. Before it starts, CLI takes a safety backup of the current data, so you can undo it.

Branches with scrubbed data

A branch is a new database with a copy of the data, where columns that look like personal data (emails, names, phone numbers and so on) are replaced with fake values. Fake emails stay unique, so joins and logins still work. Use a branch for experiments and migrations you aren't sure of, never production.

In the dashboard: the Backups tab has Branch this database.

With the API:

API
GET /v1/services/:id/scrub-plan
POST /v1/services/:id/branch
JSON
{ "scrub": "auto" }

The scrub plan shows which columns will be replaced. Poll GET /v1/branches/:id until it's done.

Point-in-time recovery

Postgres can keep its history, so you can get the data back as it was at any second. Turning it on restarts the database briefly.

A restore goes into a new database replayed to the time you choose. The original is never touched, so you can compare before switching your app over.

In the dashboard: the Backups tab has a Point-in-time recovery section.

With the API:

API
PUT /v1/services/:id/point-in-time
POST /v1/services/:id/restore-to
JSON
{ "at": "2026-11-08T03:12:00Z" }

Rehearse a migration

If your app has a release command (usually migrations), you can run it against a throwaway copy of the database before deploying. See Previews and safe releases.

API
POST /v1/services/:id/rehearse
GET /v1/rehearsals/:id

The rehearsal ends as passed or failed, with the command's output.

High availability for Postgres

Add standbys that take over if the primary stops answering, and read replicas that serve reads. Each standby and replica is a full copy with its own volume, billed at the database's full size, so two standbys triple the cost. Only admins can change this.

In the dashboard: the database's Backups tab has a high-availability panel with the number of standbys and read replicas, and the cost before you save.

Ask your agent:

"Add one standby to postgres. Show me the cost first."

With the API:

API
PUT /v1/services/:id/ha
GET /v1/services/:id/ha
JSON
{ "standbys": 1, "readReplicas": 1 }

You can have up to 2 standbys and 3 read replicas. GET shows each member, its role and how far behind it is. Apps reach the read replicas with ${{postgres.READ_URL}}.

What happens when the primary fails

  1. CLI checks the primary every 15 seconds.
  2. After two missed checks, it stops the old primary for good, so two primaries can never both accept writes.
  3. Only then does it promote the standby that received the most data.
  4. The database's address moves to the new primary, so DATABASE_URL keeps working without a redeploy.
  5. The old primary's data is rebuilt as a new standby.
  6. A database_failover event fires, and the change appears in the flight recorder.

Switch over by hand

For maintenance, you can switch to a standby yourself. The old primary shuts down cleanly first, handing its last changes to the standbys, and only a standby that has caught up is chosen. Connections drop for a few seconds.

In the dashboard: press Switch over now in the high-availability panel.

With the API:

API
POST /v1/services/:id/failover