Get started

Databases

keel.run runs managed Postgres 17 and 18 (default 18) with CloudNativePG. Each database is its own Postgres cluster in your environment, on local NVMe storage, with daily backups and point-in-time recovery.

Plans

Plan vCPU RAM Storage (default / max) Instances Point-in-time recovery
pg-xs 0.25 256 MB 1 GB / 10 GB 1 7 days
pg-s (default) 0.5 1 GB 10 GB / 100 GB 1 7 days
pg-m 1 2 GB 25 GB / 250 GB 1 14 days
pg-m-ha (Pro) 1 2 GB 25 GB / 250 GB 2 (primary + standby, automatic failover) 14 days

A database is billed like an app: RAM by reservation, CPU by use, plus storage. See Pricing.

Storage can grow at any time (never shrink). Changing the plan restarts the instances; with pg-m-ha the standby is promoted first.

Create a database

In the dashboard: New → Database in an environment. Or with the CLI or API:

keel db create main --plan pg-s            # --version 17|18, --storage <GB>
keel db list
curl -X POST https://api.keel.run/v1/environments/env_…/databases \
  -H "Authorization: Bearer $KEEL_TOKEN" -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name": "main", "plan": "pg-s"}'

The status goes provisioning → available, usually within a few minutes. Other states: restoring, degraded (one instance is unhealthy), paused (the workspace is suspended), failed, deleting.

The database has one database and one owner role, both called app. There is no superuser.

Linking writes the database's internal connection URL into a service's variables (default name DATABASE_URL) and redeploys the service:

curl -X POST https://api.keel.run/v1/databases/db_…/link \
  -H "Authorization: Bearer $KEEL_TOKEN" -H "Content-Type: application/json" \
  -d '{"service_id": "svc_…"}'

Without service_id, the variable is set for every service in the environment. Pass "variable": "PG_URL" for another name, or "redeploy": false to roll out later. In the dashboard, use Link on the database page.

Inside the environment, traffic to the database never leaves your environment's private network. When you rotate the password, keel.run updates every linked variable and redeploys the services that use it.

Connect from your machine

Every database is reachable from the internet through keel-pgproxy on port 5432 – over TLS only. The proxy reads the database from the TLS server name (SNI), so all databases share one address:

postgres://app:<password>@db-01j….pg.keel.run:5432/app?sslmode=require

Get the URL (it contains the password, and every read is recorded in the audit log), or open psql directly:

keel db url main          # prints the connection URL
keel db connect main      # runs psql; the password is passed via PGPASSWORD, not the command line

Notes for clients:

  • TLS is required. Use sslmode=require or stricter; plain-text connections are refused. With sslmode=verify-full your client checks the certificate of *.pg.keel.run.
  • SNI: libpq 14 and newer (psql, most drivers built on it) and most native drivers send the host name automatically. Postgres 17+ clients can also use sslnegotiation=direct.
  • Clients without SNI: add options=endpoint=<database id> to the connection string, or use app.<database id> as the user name.
  • The proxy limits connections per IP address and per database. Use a connection pool in long-running apps.

Read-only SQL for agents

POST /v1/databases/{id}/query (and the MCP tool run_sql) runs a single statement in a read-only transaction as a separate role that can read your data but cannot write, with a 5-second timeout and at most 500 rows. The audit log records a hash of the statement, not its text. It needs the databases:query scope.

Backups and restores

  • A base backup runs every day, and the write-ahead log is archived continuously to object storage at Hetzner, so you can restore to any point in time within the plan's recovery window.
  • GET /v1/databases/{id}/backups lists the backups and the earliest point you can restore to.
  • A restore always creates a new database; the original is never overwritten. This also works for a database you deleted, as long as it is within the recovery window.
curl -X POST https://api.keel.run/v1/databases/db_…/restore \
  -H "Authorization: Bearer $KEEL_TOKEN" -H "Content-Type: application/json" \
  -d '{"to_time": "2026-11-17T09:30:00Z", "name": "main-restored"}'

Without to_time, the newest possible state is restored. Check the restored data, then link the new database to your service.

Delete a database

Deleting needs the admin scope (agents must confirm it in a second step). The database stops at once; its backups stay available for restores until the recovery window has passed.

View as Markdown