Datenbank und Migrationen

Datenbank und Migrationen

Verbindungen und Rollen

• DATABASE_URL ist die privilegierte Verbindung für Alembic.
• APP_DATABASE_URL ist die eingeschränkte Laufzeitverbindung des Haupt-Backends.
• ABGABEBOX_DATABASE_URL verwendet die stark eingeschränkte Rolle hocx_abgabebox.

Migrationen dürfen Berechtigungen der Laufzeitrollen nicht versehentlich erweitern.

Neue Migration erstellen

Im laufenden Entwicklungs-Stack:

docker compose -p hocx-dev exec backend \
  alembic revision --autogenerate -m "kurze_beschreibung"

Die generierte Datei unter backend/alembic/versions/ muss immer manuell geprüft werden. Autogenerate erkennt keine fachlichen Backfills, sicheren Rollout-Reihenfolgen oder gewünschten Rollenrechte.

Migration prüfen

docker compose -p hocx-dev exec backend alembic current
docker compose -p hocx-dev exec backend alembic heads
docker compose -p hocx-dev exec backend alembic upgrade head
./scripts/test.sh backend
bash scripts/tests/test_release_config.sh

Die CI führt alembic upgrade head zusätzlich gegen eine vollständig frische PostgreSQL-16-Datenbank aus.

Regeln

1. Jede Schemaänderung erhält eine Alembic-Migration.
2. Runtime-Code darf Tabellen oder Spalten nicht beim Start erzeugen.
3. Constraints und Indizes werden explizit benannt.
4. Fremdschlüssel und häufige Tenant-/Sortierabfragen erhalten passende Indizes.
5. Neue mandantenbezogene Tabellen tragen tenant_id oder besitzen eine eindeutig tenant-gescopte Beziehung.
6. Datenmigrationen sind deterministisch und wiederholbar zu prüfen.
7. Grosse Backfills werden in Batches oder kontrollierten Schritten ausgeführt.
8. Rollen/GRANTs der Hauptanwendung und Abgabebox werden mitgetestet.

Rückwärtskompatible Schemaänderungen

Riskante Änderungen werden über zwei Releases verteilt:

1. neue Spalte/Tabelle ergänzen und Code kompatibel mit alt und neu ausrollen;
2. Daten backfillen und verifizieren;
3. Leser auf das neue Schema umstellen;
4. erst in einem späteren Release alte Spalten/Constraints entfernen.

Ein Code-Rollback kann eine destruktive Migration nicht rückgängig machen. Vor jedem Deployment wird deshalb ein Datenbankbackup erstellt; Restore steht im Deployment-Runbook.

Datenmodell-Konventionen

• interne Primärschlüssel bleiben intern;
• APIs verwenden public_id;
• Geldwerte verwenden Numeric/Decimal, nicht Float-Persistenz;
• Zeitpunkte werden eindeutig und timezone-bewusst behandelt;
• Unique-Constraints sichern fachliche Eindeutigkeit auch bei Nebenläufigkeit;
• konkurrierende Buchungs-/Quota-Abläufe verwenden Locks oder atomare SQL-Operationen.

Migration testen

Mindestens prüfen:

• Upgrade von der vorherigen Revision;
• Upgrade einer leeren Datenbank bis head;
• vorhandene Daten nach einem Backfill;
• Constraints und Indizes;
• Laufzeitzugriff mit hocx_app;
• erlaubte und verbotene Aktionen mit hocx_abgabebox;
• Anwendungstest für das geänderte Verhalten.

Produktive Migrationen werden nicht nachträglich verändert. Korrekturen erfolgen in einer neuen Revision.