Plan OpsKnight database connections

OpsKnight needs a direct PostgreSQL path for migrations and non-Web responsibilities. Split deployments can additionally give Web a transaction-pooled PgBouncer path.

Connection variables

DATABASE_URL is the normal application database URL.
DIRECT_DATABASE_URL bypasses transaction pooling and is required wherever direct PostgreSQL behavior is needed.
WEB_DATABASE_URL is the optional Web-only endpoint used by supported split/PgBouncer deployment assets.

Packaging maps these values into roles differently. Inspect the rendered Compose configuration or Kubernetes manifests rather than assuming every container receives the same URL.

Migration, Scheduler, General Worker, Critical Worker, Bulk Worker, and Status Projector use direct PostgreSQL connections. Web can use PgBouncer in split mode. Do not route Prisma migrations through transaction pooling.

A representative direct external URL is:

text

postgresql://opsknight:<encoded-password>@db.example.com:5432/opsknight_db?sslmode=verify-full&sslrootcert=/etc/opsknight/db-ca.crt&connection_limit=10&pool_timeout=30

URI-encode reserved characters in credentials. Mount a private CA at the exact container path named by sslrootcert. NODE_EXTRA_CA_CERTS alone does not configure Prisma's native PostgreSQL TLS connection.

Calculate the budget

Add the maximum pool for every replica of every role, migration/administration headroom, monitoring clients, and failover overlap. Compare the total with the database service's usable connection limit. Do not allocate the provider's entire hard maximum; PostgreSQL and operational access need reserve capacity.

Use Production sizing and run the checked-in capacity validator where the packaging supports it:

node deploy/scripts/validate-runtime-capacity.cjs

External PostgreSQL requirements

Before deployment, verify:

DNS resolves from the actual workload network.
TLS validates the database hostname and trusted CA.
The application role can connect to the intended database and schema.
The migration owner has the privileges required by the release migration.
Firewall or NetworkPolicy permits every selected runtime role.
Backup, point-in-time recovery, maintenance, failover, and connection limits are known.
A restore has been tested in an isolated database.

Never use a production database to test an unreviewed deployment manifest.

PgBouncer boundary

PgBouncer is a Web scaling tool, not a way to ignore the database budget. Transaction pooling reduces persistent backend connections for Web clients but adds its own saturation and failure signals. Monitor client wait, server pool use, authentication failures, and database reachability.

Secret and recovery boundary

Database backups do not preserve application secrets. Back up ENCRYPTION_KEY, authentication/API secrets, database credentials, and private CA material separately. Restored encrypted provider credentials are unusable without the matching encryption key.