Files

master 152c1b1357 doctor: complete runtime check documentation sprint

Signed-off-by: master <>

2026-03-31 23:26:24 +03:00

2.3 KiB

Raw Blame History

checkId, plugin, severity, tags

checkId

plugin

severity

Database Connection

What It Checks

Opens a PostgreSQL connection using Doctor:Plugins:Database:ConnectionString or ConnectionStrings:DefaultConnection and runs SELECT version(), current_database(), current_user.

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.

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

ConnectionStrings__DefaultConnection is missing or malformed
PostgreSQL is not running or not listening on the configured host and port
DNS, firewall, or container networking prevents the Doctor service from reaching PostgreSQL
Username, password, database name, or TLS settings are incorrect

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

check.db.latency - uses the same connection path and highlights performance issues after basic connectivity works
check.db.pool.health - validates connection pressure after connectivity is restored

2.3 KiB Raw Blame History