Datenbankmodell

Dieses Dokument beschreibt, wo und in welcher Form Studio die Daten speichert. Es dient als Referenz, wenn Sie den Backup-Umfang festlegen oder direkt Abfragen durchführen müssen.

Es gibt zwei Speicherorte

PostgreSQL enthält die Metadaten, und das Dateisystem(DATA_ROOT) enthält App-Quellcode und Build-Artefakte. Beide müssen gesichert werden, um eine Wiederherstellung zu ermöglichen – nur die DB zu sichern bedeutet, dass der App-Code fehlt, und nur das Dateisystem zu sichern bedeutet, dass keine Informationen darüber vorliegen, wer was erstellt hat.

Speicherort	Inhalt
PostgreSQL	Benutzer · App-Metadaten · Konversationen · Audit · Watcher · Fähigkeiten
Dateisystem (DATA_ROOT)	Workspaces (App-Quellcode) · Build-Artefakte · Status

PostgreSQL läuft in einem von zwei Modi – als gebündelter Container (Standard) oder als gemeinsame Plattform-PG. Siehe Umgebungsvariablen-Referenz.

---

Tabellen – 11 Stück

Gruppe	Tabelle	Inhalt
Benutzer	studio_users	Konten · Rollen (admin/builder/viewer) · Passwort-Hashes
	studio_tokens	Ausgestellte Tokens
Konversationen	ask_conversations	Chat-Threads
	ask_history	Gesendete und empfangene Nachrichten sowie benötigte Zeit
Watcher	watchers	Definitionen der periodischen Überwachung und Alarm-Einstellungen
	notification_seen	Status der Alarm-Bestätigung
Fähigkeiten	skills	Registrierte Vor-Ort-Expertise
Bereitstellung	deploy_log	Bereitstellungsverlauf
Audit · Nutzung	audit_log	Wer hat was getan
	usage_log	AI-Token-Verbrauch
Schema	schema_migrations	Angewendete Migrationsnamen und Zeitpunkte

Im Migrationsprotokoll ist flows sichtbar

Auch bei Neuinstallationen wird der Ablauf durchlaufen, bei dem zunächst flows erstellt und dann in watchers umbenannt wird – da der Migrationsverlauf einmal geschrieben und nicht mehr geändert wird. Wenn Sie direkt Abfragen ausführen, ist es watchers.

---

Schemaänderungen werden durch Migrationen verwaltet

Beim Serverstart wendet src/infra/db/migrations/ die .sql in numerischer Reihenfolge an und protokolliert die angewendeten Dateinamen in schema_migrations. Bereits angewendete Migrationen werden nicht erneut ausgeführt.

-- 지금 어디까지 적용됐는지
SELECT name, applied_at FROM schema_migrations ORDER BY name;

Manuelle Schemaänderungen vermeiden

Wenn schema_migrations und das tatsächliche Schema voneinander abweichen, schlägt die Migration beim nächsten Upgrade fehl, weil sie versucht, eine bereits vorhandene Struktur zu erstellen. Der Bildschirmstart wird komplett blockiert.

Vor dem Upgrade sollten Sie zuerst ein Backup erstellen → Backup und Wiederherstellung.

---

Dateisystem – DATA_ROOT

Der Standardwert ist /var/lib/pp-studio. Folgendes wird vollständig darin abgelegt:

Inhalt	Falls fehlend
App-Workspaces (generierter Quellcode)	App lässt sich nicht öffnen – die DB enthält nur Metadaten
Build-Artefakte	Neu erstellen ist möglich
Sitzungen · Status	Laufende Arbeiten gehen verloren

Die DB befindet sich nicht unter DATA_ROOT

Studio verwendet eine externe PostgreSQL-Instanz. Selbst wenn Sie DATA_ROOT vollständig sichern, muss die DB separat gesichert werden – siehe Backup und Wiederherstellung.

---

Häufig übersehene Punkte beim Backup

Was gesichert werden muss	Falls vergessen
PostgreSQL-Dump	Konten · Watcher · Konversationen · Audit-Aufzeichnungen gehen verloren
DATA_ROOT	App-Quellcode fehlt, App lässt sich nicht öffnen
/etc/kopens/plantpulse-studio.env	Zugangsdaten und Schlüssel müssen erneut eingegeben werden

Testen Sie die Wiederherstellung mindestens einmal

Der gefährlichste Zustand ist, wenn ein Backup existiert, aber die Wiederherstellung noch nie getestet wurde. Die Anleitung finden Sie unter Backup und Wiederherstellung.

---

Verwandte Dokumente

• Backup und Wiederherstellung
• Umgebungsvariablen-Referenz – DB-Modus und DATA_ROOT
• Passwort · API-Schlüssel ändern – Rotation des AI-Schlüssels (DB-Zugriff über DATABASE_URL)
• Initiales Passwort ändern – Bootstrap-Administratorkonto