データベースモデル

スタジオがデータをどこにどのような形で格納するかをまとめたドキュメントです。バックアップ範囲を決めたり、直接クエリを実行したりする際に参照します。

ストレージは2つあります

PostgreSQL にはメタデータが格納され、ファイルシステム(DATA_ROOT)にはアプリのソースとビルド成果物が格納されます。両方を取得して初めて復元できます — DB だけではアプリコードがなく、ファイルだけでは誰が何を作成したかがわかりません。

ストレージ	格納するもの
PostgreSQL	ユーザー・アプリメタ・会話・監査・ウォッチャー・スキル
ファイルシステム (`DATA_ROOT`)	ワークスペース(アプリソース)・ビルド成果物・状態

PostgreSQL は2つのモードのいずれかです — バンドルコンテナ(デフォルト)またはプラットフォーム共有 PG。環境変数リファレンスを参照してください。

テーブル — 11個

グループ	テーブル	格納するもの
ユーザー	`studio_users`	アカウント・ロール(`admin`/`builder`/`viewer`)・パスワードハッシュ
	`studio_tokens`	発行済みトークン
会話	`ask_conversations`	チャットスレッド
	`ask_history`	送受信メッセージと所要時間
ウォッチャー	`watchers`	定期監視定義と通知設定
	`notification_seen`	通知確認状態
スキル	`skills`	現場ノウハウ登録版
デプロイ	`deploy_log`	デプロイ履歴
監査・使用量	`audit_log`	誰が何をしたか
	`usage_log`	AI トークン使用量
スキーマ	`schema_migrations`	適用済みマイグレーション名と日時

マイグレーションログには flows が表示されます

新規インストールも flows で作成した後、watchers にリネームする手順を踏みます — マイグレーション履歴は一度記録されると変更されないためです。直接クエリを実行する場合は watchers です。

サーバー起動時に src/infra/db/migrations/ の .sql を番号順に適用し、適用したファイル名を schema_migrations に記録します。適用済みのものは再度実行されません。

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

スキーマを手で変更しないでください

schema_migrations と実際のスキーマが一致しない場合、次のアップグレードでマイグレーションが「既存のものを作成しようとして」失敗します。画面起動全体がブロックされます。

アップグレード前にはバックアップを先に取得してください → バックアップと復元。

デフォルト値は /var/lib/pp-studio です。以下がすべてこの中に格納されます。

DB は DATA_ROOT にありません

スタジオは外部 PostgreSQL を使用します。DATA_ROOT を丸ごとバックアップしても DB は別途 取得する必要があります — バックアップと復元を参照してください。

取得すべきもの	漏らした場合
PostgreSQL ダンプ	アカウント・ウォッチャー・会話・監査記録が失われる
`DATA_ROOT`	アプリソースが失われ、アプリを開けなくなる
`/etc/kopens/plantpulse-studio.env`	接続情報・キーを再設定する必要がある

復元を一度は実行してみてください

バックアップのみで復元を試したことがない状態が最も危険です。手順はバックアップと復元に記載されています。