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.
Connect
Section titled “Connect”DATABASE_URLWhere Postgres is, for example postgres://circi:password@db.internal:5432/circi. The server and the worker both read it.
DATABASE_POOL_MAXThe 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.
Connection rules
Section titled “Connection rules”If a connection drops, the process reconnects by itself.
What is stored
Section titled “What is stored”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.
Migrations
Section titled “Migrations”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.
-
Back up first. See Backups.
-
Pull the new image and restart. The first process to start applies the migrations.
-
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.
Health
Section titled “Health”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.