checkId: check.db.connection plugin: stellaops.doctor.database severity: fail tags: [database, postgres, connectivity, quick]

Database Connection

This Doctor check is the fastest way for an operator to confirm that the Doctor service can reach PostgreSQL at all. It is the prerequisite for every other database check: if it fails, migrations, pool, and schema diagnostics cannot run.

What It Checks

Opens a PostgreSQL connection using Doctor:Plugins:Database:ConnectionString, ConnectionStrings:DefaultConnection, or the platform key ConnectionStrings:StellaOps (compose ConnectionStrings__StellaOps) and runs SELECT version(), current_database(), current_user. The ConnectionStrings__StellaOps key is what the standard doctor-web deployment sets, so the database checks resolve on the real environment instead of silently skipping.

The check passes only when the connection opens and the probe query returns successfully. Connection failures, authentication failures, DNS errors, and network timeouts fail the check. For cataloged tenants, tenant connection-string overrides under Doctor:TenantOverrides:<tenant>:<key> or Tenants:<tenant>:<key> are checked before global connection strings, so a healthy default database path does not hide a second tenant whose connection path fails.

Transient connection exceptions are retried with bounded ProbeRetry; returned query failures are not retried. Tenant fan-out evidence includes per-tenant severity and retry attempt counts.

Why It Matters

Doctor cannot validate migrations, pool health, or schema state if the platform cannot reach PostgreSQL. A broken connection path usually means startup failures, API errors, and background job disruption across the suite.

Common Causes

How to Fix

Docker Compose

docker compose -f devops/compose/docker-compose.stella-ops.yml ps postgres
docker compose -f devops/compose/docker-compose.stella-ops.yml logs --tail 100 postgres
docker compose -f devops/compose/docker-compose.stella-ops.yml exec postgres pg_isready -U stellaops -d stellaops

Set the Doctor connection string with compose-style environment variables:

services:
  doctor-web:
    environment:
      ConnectionStrings__DefaultConnection: Host=postgres;Port=5432;Database=stellaops;Username=stellaops;Password=${STELLAOPS_DB_PASSWORD}

Bare Metal / systemd

pg_isready -h <db-host> -p 5432 -U <db-user> -d <db-name>
psql "Host=<db-host>;Port=5432;Database=<db-name>;Username=<db-user>;Password=<password>" -c "SELECT 1"

Kubernetes / Helm

kubectl exec deploy/doctor-web -- pg_isready -h <postgres-service> -p 5432 -U <db-user> -d <db-name>
kubectl get secret <db-secret> -o yaml

Verification

stella doctor --check check.db.connection