60 lines
2.9 KiB
Markdown
60 lines
2.9 KiB
Markdown
|
# 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.
|