infra/stacks/sql/README.md

# sql

Central configuration database — the "single point of config" backing Keycloak, Gitea, MLflow, and any stack that needs a relational store. **Cloud-only.**

- **Engine**: postgres 16-alpine
- **Network**: `data` only (no internet egress)
- **Volume**: `sql-data` (PGDATA)
- **Init scripts**: `config/init.d/*.sh` runs once on first container start

## Per-app databases

On first start, `config/init.d/01-databases.sh` provisions:

| Database | Owner role | Used by |
|---|---|---|
| `gitea` | `gitea` | gitea stack |
| `keycloak` | `keycloak` | keycloak stack |
| `mlflow` | `mlflow` | mlflow stack |

Passwords come from env vars (`GITEA_DB_PASSWORD`, `KEYCLOAK_DB_PASSWORD`, `MLFLOW_DB_PASSWORD`) which must be set in the cloud `.env` *before* first start.

**Important**: init scripts only run when `sql-data` is empty. Changing the script after first start has no effect until the volume is wiped. To add a new app DB later, connect with `psql` and create it manually, then update this script for fresh deploys.

## Reset / re-init

```bash
docker compose down
docker volume rm cloud_sql-data       # ⚠ destroys all data
docker compose up -d
```

## TODO

- Backup strategy (pg_dump cron sidecar vs streaming replica vs WAL archiving to MinIO)
- Per-app least-privilege grants (currently each role owns its DB only — fine for now)
- Monitoring (postgres_exporter for Prometheus when observability stack lands)