118 lines
4.1 KiB
Markdown
118 lines
4.1 KiB
Markdown
|
# Migration & Deploy – Designprinzipien (Extraktion)
|
|||
|
|
|
|||
|
|
**Status:** Analyse / Arbeitspapier
|
|||
|
|
**Stand:** 2026-07-04
|
|||
|
|
**Geltungsbereich:** Modul „Migration & Deploy“ — Schema-Evolution, Container-Start
|
|||
|
|
|
|||
|
|
**Serie:** Designprinzipien für Produktfamilie · Shinkan Dokument 13 von 15
|
|||
|
|
**Mitai-Vergleich:** [MIGRATION_DEPLOY_DESIGN_PRINCIPLES.md](file:///c:/Dev/mitai-jinkendo/.claude/docs/technical/MIGRATION_DEPLOY_DESIGN_PRINCIPLES.md) (#9)
|
|||
|
|
|
|||
|
|
**Kernkomponenten:**
|
|||
|
|
|
|||
|
|
| Bereich | Pfade |
|
|||
|
|
|---------|-------|
|
|||
|
|
| DB-Init | `backend/db_init.py` |
|
|||
|
|
| Migrationen | `backend/migrations/XXX_*.sql` |
|
|||
|
|
| Version | `backend/version.py` (`DB_SCHEMA_VERSION`, `MODULE_VERSIONS`) |
|
|||
|
|
| Docker | `docker-compose.yml`, `docker-compose.dev-env.yml` |
|
|||
|
|
| Deploy | develop → dev.shinkan · main → shinkan (Pi) |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Modul
|
|||
|
|
|
|||
|
|
**Migration & Deploy**
|
|||
|
|
|
|||
|
|
Nummerierte SQL-Migrationen beim Container-Start, Tracking in `schema_migrations`, Git-Branch → Umgebung, fail-fast ohne Auto-Rollback.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Designprinzipien
|
|||
|
|
|
|||
|
|
### 1. Nummerierte Migrationen `XXX_*.sql`
|
|||
|
|
|
|||
|
|
| | |
|
|||
|
|
|---|---|
|
|||
|
|
| **Prinzip** | Nur nummerierte Dateien in `backend/migrations/`; lexikographische Reihenfolge. |
|
|||
|
|
| **Begründung** | Familien-Standard Mitai/Shinkan; vorhersagbare Anwendung. |
|
|||
|
|
| **Quelle** | `db_init.py`; `CLAUDE.md` |
|
|||
|
|
| **Tragfähigkeit** | **hoch** |
|
|||
|
|
| **Einschränkung** | Manuelle Nummern-Kollisionen vermeiden — Team-Disziplin. |
|
|||
|
|
|
|||
|
|
### 2. Startup vor App — Migrationen blockieren Start bei Fehler
|
|||
|
|
|
|||
|
|
| | |
|
|||
|
|
|---|---|
|
|||
|
|
| **Prinzip** | `db_init.py` wartet auf Postgres, wendet fehlende Migrationen an, dann FastAPI. |
|
|||
|
|
| **Begründung** | Keine App mit veraltetem Schema. |
|
|||
|
|
| **Quelle** | Container-Entrypoint / startup |
|
|||
|
|
| **Tragfähigkeit** | **hoch** |
|
|||
|
|
| **Einschränkung** | Kein automatisches Rollback — manuelle Recovery. |
|
|||
|
|
|
|||
|
|
### 3. `schema_migrations` Tracking-Tabelle
|
|||
|
|
|
|||
|
|
| | |
|
|||
|
|
|---|---|
|
|||
|
|
| **Prinzip** | Jede angewendete Datei wird persistiert; Wiederholung überspringt Bekannte. |
|
|||
|
|
| **Begründung** | Idempotenz über Deploys hinweg. |
|
|||
|
|
| **Quelle** | `ensure_migration_table`, `get_applied_migrations` |
|
|||
|
|
| **Tragfähigkeit** | **hoch** |
|
|||
|
|
| **Einschränkung** | Geänderte Migration nach Apply — nicht neu ausführen (neue Nummer). |
|
|||
|
|
|
|||
|
|
### 4. `DB_SCHEMA_VERSION` als dokumentierter Stand
|
|||
|
|
|
|||
|
|
| | |
|
|||
|
|
|---|---|
|
|||
|
|
| **Prinzip** | `version.py` führt Schema-Version; MODULE_VERSIONS für Subsysteme. |
|
|||
|
|
| **Begründung** | Support und Handover wissen erwarteten Stand. |
|
|||
|
|
| **Quelle** | `backend/version.py` |
|
|||
|
|
| **Tragfähigkeit** | **hoch** |
|
|||
|
|
| **Einschränkung** | Manuell pflegen bei Migration — Drift möglich. |
|
|||
|
|
|
|||
|
|
### 5. develop/main → Dev/Prod mit festen Ports
|
|||
|
|
|
|||
|
|
| | |
|
|||
|
|
|---|---|
|
|||
|
|
| **Prinzip** | Dev 3098/8098 · Prod 3003/8003 — nie ändern ohne explizite Freigabe. |
|
|||
|
|
| **Begründung** | Deploy-Infrastruktur auf Pi/Synology stabil. |
|
|||
|
|
| **Quelle** | `CLAUDE.md` Deployment |
|
|||
|
|
| **Tragfähigkeit** | **hoch** |
|
|||
|
|
| **Einschränkung** | — |
|
|||
|
|
|
|||
|
|
### 6. Neue Spalten nur via Migration
|
|||
|
|
|
|||
|
|
| | |
|
|||
|
|
|---|---|
|
|||
|
|
| **Prinzip** | Kein ad-hoc ALTER in Routern; Coding Rules. |
|
|||
|
|
| **Begründung** | Reproduzierbare Umgebungen. |
|
|||
|
|
| **Quelle** | `.claude/rules/CODING_RULES.md` |
|
|||
|
|
| **Tragfähigkeit** | **hoch** |
|
|||
|
|
| **Einschränkung** | — |
|
|||
|
|
|
|||
|
|
### 7. IF NOT EXISTS / defensive SQL wo sinnvoll
|
|||
|
|
|
|||
|
|
| | |
|
|||
|
|
|---|---|
|
|||
|
|
| **Prinzip** | Migrationen tolerant bei Wiederanlauf in Dev — aber Tracking verhindert Doppel-Apply. |
|
|||
|
|
| **Begründung** | Recovery in Entwicklung erleichtern. |
|
|||
|
|
| **Quelle** | Mitai-Migrations-Muster |
|
|||
|
|
| **Tragfähigkeit** | **mittel** |
|
|||
|
|
| **Einschränkung** | Nicht alles idempotent — komplexe Migrationen brauchen Transaktion. |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Nicht übernehmen
|
|||
|
|
|
|||
|
|
1. **Manuelle psql-Schritte in Prod** ohne nummerierte Migration im Repo.
|
|||
|
|
2. **Schema-Drift nur in schema.sql** ohne Migration — Init vs. Upgrade verwechseln.
|
|||
|
|
3. **Auto-Rollback bei fehlgeschlagener Migration** — fail-fast, manuell fixen.
|
|||
|
|
4. **Port-Änderung ohne Infra-Update** — bricht Fritz!Box/NAS-Routing.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Verwandte Dokumentation
|
|||
|
|
|
|||
|
|
- [DATABASE_SCHEMA.md](../../../.claude/docs/technical/DATABASE_SCHEMA.md)
|
|||
|
|
- Mitai: [MIGRATION_DEPLOY_DESIGN_PRINCIPLES.md](file:///c:/Dev/mitai-jinkendo/.claude/docs/technical/MIGRATION_DEPLOY_DESIGN_PRINCIPLES.md)
|
|||
|
|
- [DESIGN_PRINCIPLES_INDEX.md](./DESIGN_PRINCIPLES_INDEX.md)
|