# ProofedMesh Database Layer

Alle Postgres-Schemas von ProofedMesh werden mit **[golang-migrate](https://github.com/golang-migrate/migrate)** versioniert. Entscheidungsgrundlage: siehe [ADR-0004](../docs/adr/0004-db-migrations.md).

## Layout

```
db/
├── README.md              — diese Datei
├── trust/
│   └── migrations/
│       ├── 0001_per_diem_rates.up.sql
│       └── 0001_per_diem_rates.down.sql
└── expense/
    └── migrations/        — kommt im Phase-4-Rollout der DB-App
```

Jede logische Datenbank bekommt ein eigenes `migrations/`-Verzeichnis. Die Migrationstabelle (`schema_migrations`) wird je Datenbank separat gepflegt. Pro Postgres-Instanz können mehrere logische Schemas liegen — die Migrationen schreiben SQL mit `CREATE SCHEMA IF NOT EXISTS` und `SET search_path`.

## Konventionen

- Dateinamen: `NNNN_description.up.sql` + `.down.sql` (vierstellige Nummer, Snake-Case).
- Nummerierung streng monoton. Fehlerhafte Migrationen werden nie umnummeriert — immer durch eine neue Migration korrigiert.
- Immutable Business-Felder werden per `BEFORE UPDATE`-Trigger gesichert (siehe `per_diem_rates`).
- Postgres-Extensions werden am Anfang der Migration eingezogen (`CREATE EXTENSION IF NOT EXISTS …`).
- Jede `up.sql` MUSS ein `down.sql` haben; die `down.sql` DARF im Business-Fall unvollständig oder destruktiv sein, muss das dann aber im Kommentar sagen.

## Lokal ausführen

Voraussetzung: eine lokale Postgres (z.B. `docker run --rm -p 5432:5432 -e POSTGRES_PASSWORD=postgres postgres:16`) und die `migrate`-CLI (`brew install golang-migrate` / `apt install migrate` / `go install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@latest`).

```bash
# Up (alle noch nicht angewandten Migrationen)
migrate -path db/trust/migrations \
  -database "postgres://postgres:postgres@localhost:5432/trust?sslmode=disable" up

# Down um eine Version
migrate -path db/trust/migrations \
  -database "postgres://postgres:postgres@localhost:5432/trust?sslmode=disable" down 1

# Aktuelle Version anzeigen
migrate -path db/trust/migrations \
  -database "postgres://postgres:postgres@localhost:5432/trust?sslmode=disable" version
```

## In Prod

- Rollout als dedizierter Kubernetes-Job (`job-migrate-trust`) VOR dem Rolling-Update der trust-api-Pods. Siehe [ADR-0004 → Ausführungsmodell](../docs/adr/0004-db-migrations.md#ausführungsmodell).
- Trust-API startet nur, wenn `schema_migrations.dirty = false` und die höchste Version die vom Code erwartete erreicht.
- Rollback ist ein manueller Prozess mit CTO-Freigabe.

## CI

Ein eigener CI-Job `db` (noch nicht committed) macht:
1. **Lint** (`sqlfluff` oder `pg_format`).
2. **Dry-run** auf einer wegwerfbaren Postgres-Instanz: `up` → `down` → `up`, muss grün sein.
3. **Keine History-Rewrites:** vorhandene Dateien dürfen in einem PR nicht geändert werden.

Kommt in einem separaten Heartbeat.