Migrationen ausführen und upgraden

SupaCloud verwendet sqlx-Migrationen mit fortlaufender Nummerierung in server/migrations/. Der Server führt alle ausstehenden Migrationen automatisch beim Start aus – du musst Migrationen nicht manuell ausführen. Diese Anleitung beschreibt die sichere Upgrade-Reihenfolge: zuerst sichern, dann das neue Image ziehen und neu starten.

Voraussetzungen

Du benötigst Schreibzugriff auf den Host, auf dem der Docker-Compose-Stack läuft.
Stelle sicher, dass der Stack vor dem Upgrade fehlerfrei läuft:
Terminal window
```
docker compose -f docker-compose.yml -f compose.standalone.yml ps
```
Alle Dienste sollten healthy oder running anzeigen. Upgrade einen fehlerhaften Stack nicht.

1. PostgreSQL-Volume sichern

Der Datenbankzustand liegt im Docker-Volume postgres-data. Sichere es, bevor du ein neues Image ziehst.

Server stoppen (Postgres weiterlaufen lassen, damit der Dump konsistent ist):
Terminal window
```
docker compose -f docker-compose.yml -f compose.standalone.yml stop server
```

Datenbank in eine lokale Datei dumpen:

docker compose -f docker-compose.yml -f compose.standalone.yml \
  exec postgres \
  pg_dump -U supacloud supacloud \
  > supacloud-backup-$(date +%Y%m%d-%H%M%S).sql

Ersetze supacloud durch deine POSTGRES_USER- / POSTGRES_DB-Werte aus der .env-Datei, falls du die Standardwerte geändert hast.

Überprüfe, ob die Dump-Datei nicht leer ist, bevor du fortfährst.

2. Neues Image ziehen und neu starten

Neues Image ziehen:

docker compose -f docker-compose.yml -f compose.standalone.yml pull server

Stack starten:
Terminal window
```
docker compose -f docker-compose.yml -f compose.standalone.yml up -d
```
Der server-Dienst wartet auf den Health-Check von postgres, führt dann alle ausstehenden Migrationen aus und öffnet anschließend den HTTP-Port. Beobachte das Log, um den Ablauf zu bestätigen:
Terminal window
```
docker compose -f docker-compose.yml -f compose.standalone.yml logs -f server
```
Du solltest eine Zeile ähnlich der folgenden sehen:
```
Database migrations complete
```

Stack-Status überprüfen:

docker compose -f docker-compose.yml -f compose.standalone.yml ps

Was tun, wenn eine Migration fehlschlägt

Wenn der Server mit Migration failed: im Log beendet wird:

Starte den Server nicht in einer Schleife neu – jeder Neustart wiederholt dieselbe Migration und kann das Schema in einem inkonsistenten Zustand hinterlassen.

Stelle die Sicherung aus Schritt 1 wieder her und untersuche dann den Fehler, bevor du es erneut versuchst:

docker compose -f docker-compose.yml -f compose.standalone.yml \
  exec postgres \
  psql -U supacloud supacloud < supacloud-backup-YYYYMMDD-HHMMSS.sql

Erstelle ein Issue mit der vollständigen Fehlermeldung der Migration und dem Dateinamen der Migration (Format: NNN_beschreibung.sql).