Skip to content

Configure

Database

Postgres requirements, connections, migrations and what lives in it.

CirCI needs one Postgres database. Postgres holds all of its data except the files, which live in storage. The compose file runs postgres:18-alpine with its data in the pgdata volume (Postgres 18 images keep data under /var/lib/postgresql/<major>/, so mount the volume at /var/lib/postgresql). A managed Postgres works as well.

DATABASE_URLRequiredURL

Where Postgres is, for example postgres://circi:password@db.internal:5432/circi. The server and the worker both read it.

DATABASE_POOL_MAXnumberDefault 10

The most connections one process keeps open. A server and a worker each take up to this many, so a managed database needs room for the sum across every process you run.

If a connection drops, the process reconnects by itself.

What lives in Postgres and what doesn'tPostgres holds accounts, workspaces, projects, builds and screenshot records, reviews and comments, integration connections with encrypted credentials, webhooks and their deliveries, the job queue and the instance settings. The screenshot, diff and site files are in storage, not in the database.PostgresAccounts, workspaces, projectsBuilds and screenshot recordsReviews, comments, review requests and rulesIntegration connections (credentials encrypted)Webhooks and their deliveriesJob queue, instance settings (secrets sealed)StorageScreenshots, diffs,thumbnails, hosted sitesfs or s3

The job queue lives in the same database as the data, so a webhook delivery or a check run is queued in the same step as the change that caused it: both happen or neither does.

SQL migrations live in packages/db/migrations (/app/migrations in the image). circi serve, circi worker and circi all apply pending migrations on start unless you pass --no-migrate.

  1. Back up first. See Backups.

  2. Pull the new image and restart. The first process to start applies the migrations.

  3. Migrate separately. To apply migrations without serving:

    Terminal window
    docker compose exec circi circi migrate

See Upgrades and migrations for the order to follow when you run several processes.

circi admin doctor reports whether the database is reachable and how many migrations are applied. Instance › Health shows the same under Services, and the queue depth under Background jobs. GET /readyz fails when the database can't be reached.