doctor: complete runtime check documentation sprint

Signed-off-by: master <>

docs/doctor/articles/postgres/db-connection.md

@@ -0,0 +1,60 @@
+---
+checkId: check.db.connection
+plugin: stellaops.doctor.database
+severity: fail
+tags: [database, postgres, connectivity, quick]
+---
+# 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
+```bash
+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:
+
+```yaml
+services:
+  doctor-web:
+    environment:
+      ConnectionStrings__DefaultConnection: Host=postgres;Port=5432;Database=stellaops;Username=stellaops;Password=${STELLAOPS_DB_PASSWORD}
+```
+
+### Bare Metal / systemd
+```bash
+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
+```bash
+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
+```bash
+stella doctor --check check.db.connection
+```
+
+## Related Checks
+- `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