Skip to content

Storage

All state lives in PostgreSQL 14 or newer: the directory, runbooks and their versions, runs and their events, webhook deliveries and, by default, blobs. Any PostgreSQL works: your own, RDS, Cloud SQL, Neon and others.

Variable
DATABASE_URL The connection URL. Add ?sslmode=verify-full for a managed database, and sslrootcert=<file> for a CA that isn’t public
DATABASE_URL_DIRECT A direct connection for the live-event listener (LISTEN), when DATABASE_URL goes through a transaction-mode pooler
RUNBOOK_DATABASE_POOL_SIZE Most pooled connections (default 16); keep it at 12 or more. Each live event stream holds one more

The role in DATABASE_URL needs CREATE on the database: the server creates its runbook schema and the sign-in service its auth schema. The server applies its migrations at start, under an advisory lock, so any number of instances can start together.

Any number of instances can share one database: leases, event IDs and shared rate limits keep work single.

Blobs are run archives, evidence uploads and their thumbnails, and snapshots. By default they live in PostgreSQL, in chunks. To keep the database small, put them in a bucket instead:

Terminal window
RUNBOOK_BLOB_STORE=postgres

Nothing else to set. Backups of the database include every blob.

PostgreSQL stays the authority either way: each blob keeps a row with its location, size and SHA-256, so ownership, tenancy and immutability are checked in the database. A background sweeper removes objects older than an hour that have no row (from deleted runs or interrupted writes).

Switching to a bucket doesn’t move the blobs already in PostgreSQL: they keep being read from there, while new ones go to the bucket. To move them, run the copy job once with the new store configured. It copies each blob, verifies its hash, switches its location and drops its chunks, and is safe to rerun:

Terminal window
RUNBOOK_BLOB_STORE=gcs RUNBOOK_BLOB_BUCKET=my-runbook-blobs runbook-server copy-blobs