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.
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:
cli add postgres
cli db create redis --name cache --linkcli 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:
POST /v1/projects/:id/databases{ "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:
cli db link postgres
cli db link cache --var CACHE_URL
cli deployWith the API:
POST /v1/services/:appId/link{ "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:
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:
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.
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:
cli db backups postgres
cli db backup postgres
cli db restore bak_abc123With the API:
POST /v1/services/:id/backups
POST /v1/backups/:id/restore{ "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:
GET /v1/services/:id/scrub-plan
POST /v1/services/:id/branch{ "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:
PUT /v1/services/:id/point-in-time
POST /v1/services/:id/restore-to{ "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.
POST /v1/services/:id/rehearse
GET /v1/rehearsals/:idThe 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:
PUT /v1/services/:id/ha
GET /v1/services/:id/ha{ "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
- CLI checks the primary every 15 seconds.
- After two missed checks, it stops the old primary for good, so two primaries can never both accept writes.
- Only then does it promote the standby that received the most data.
- The database's address moves to the new primary, so
DATABASE_URLkeeps working without a redeploy. - The old primary's data is rebuilt as a new standby.
- A
database_failoverevent 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:
POST /v1/services/:id/failover