---
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