ProofedMesh/db/README.md

ProofedMesh Database Layer

Alle Postgres-Schemas von ProofedMesh werden mit golang-migrate versioniert. Entscheidungsgrundlage: siehe ADR-0004.

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

# 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.
• 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.