# Databases

keel.run runs managed **Postgres 17 and 18** (default 18) with [CloudNativePG](https://cloudnative-pg.io). 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](/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:

```bash
keel db create main --plan pg-s            # --version 17|18, --storage <GB>
keel db list
```

```bash
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.

## Link a database to a service

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

```bash
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:

```text
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:

```bash
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.

```bash
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.
