Datenbank-Migrationen

Orimora verwendet Drizzle ORM mit SQL-Migrationsdateien unter src/lib/server/db/migrations/.

Migrationen ausführen

# Entwicklung (nutzt DATABASE_URL aus .env)
yarn db:migrate

# Docker / Produktion (läuft automatisch beim Container-Start)
node run-migrations.mjs

Migrationen werden der Reihe nach angewendet und in drizzle.__drizzle_migrations getrackt.

In Docker-Deployments (inklusive Coolify) laufen Migrationen automatisch beim Container-Start über docker-entrypoint.sh. Kein manueller Schritt nötig.

Migration-Runner

Orimora nutzt einen eigenen Migration-Runner (run-migrations.mjs) statt drizzle-kit migrate oder drizzle-orm/postgres-js/migrator:

1. Einzelne Transaktionen: Jede Migration läuft in einer eigenen Transaktion. Wenn Migration 15 fehlschlägt, bleiben 1–14 erhalten. Der eingebaute Drizzle-Migrator packt alles in eine Transaktion — ein Fehler rollt alles zurück.

2. Sichtbare Fehler: Bei Fehlern werden Tag, PostgreSQL-Fehlercode, Detail und Hint ausgegeben. Der Standard-Migrator beendet sich oft mit Exit-Code 1 ohne klare Meldung.

3. Hash-basiertes Tracking: Der Runner nutzt Content-Hashes statt Timestamps — vermeidet Probleme mit nicht-monotonen Journal-Einträgen.

Neue Migration hinzufügen

Migrationen in Orimora sind handgeschrieben. Jede wird von Hand verfasst:

1. Die nächst-nummerierte SQL-Datei in src/lib/server/db/migrations/ anlegen (z. B. 0078_add_widget_table.sql) mit reinem SQL. IF NOT EXISTS / IF EXISTS nutzen, damit ein erneuter Lauf sicher ist.
2. Einen passenden Eintrag in src/lib/server/db/migrations/meta/_journal.json ergänzen — der Runner wendet Dateien in Journal-Reihenfolge an.
3. Das Drizzle-Schema in src/lib/server/db/schema/ von Hand synchron halten, damit die TypeScript-Typen zur neuen DB-Form passen.
4. Lokal mit yarn db:migrate anwenden und prüfen.

Achtung

Führe drizzle-kit generate (yarn db:generate) NICHT aus, um Migrationen zu erzeugen. Es difft das Schema gegen einen internen Snapshot, der gegenüber der handgeschriebenen Historie driftet, und erzeugt eine fehlerhafte, oft destruktive „Mega-Migration” (DROP/CREATE bestehender Objekte). Drizzle erzeugt CREATE TABLE / CREATE TYPE zudem ohne IF NOT EXISTS und kollidiert so mit Objekten, die eine handgeschriebene Migration bereits angelegt hat. Das Script dient nur der einmaligen Schema-Inspektion — committe seine Ausgabe nie als Migration. Schreibe SQL + Journal-Eintrag wie oben von Hand.

Tipp

Manche Operationen (GIN-Indexe, PostgreSQL-Extensions) sind ohnehin Raw-SQL — es gibt nichts zu „generieren”; schreibe sie direkt in die nummerierte Datei.

Tipp

Große Tabellen in Produktion: GIN-Indexe mit CREATE INDEX CONCURRENTLY außerhalb der Migrationsdatei ausführen — CONCURRENTLY läuft nicht in einer Transaktion.

Schema-Überblick

Tabelle	Zweck
teams	Mandanten-Isolation
users	Teammitglieder
sessions	Auth-Sessions
collections	Dokument-Gruppen
documents	Wiki-Seiten
document_revisions	Versionsverlauf
comments	Inline-Kommentare
notifications	In-App-Benachrichtigungen
audit_events	Security-Audit-Log
tags / document_tags	Tagging
stars	Lesezeichen
views	Leseverlauf
backlinks	Querverweise
webhooks	Ausgehende Webhooks
api_keys	API-Authentifizierung
team_llm_configs	KI-Provider-Konfiguration

Coolify & Produktion

• Nach jedem Deploy wendet der Container beim Start ausstehende Migrationen an.
• Schlägt eine Migration fehl, startet die App nicht — Logs in Coolify → Service → Logs prüfen.
• Manuell im Container-Terminal: node run-migrations.mjs

Siehe auch

• Installation — lokale yarn db:migrate
• Coolify Setup — automatische Migrationen beim Deploy
• Architektur