メインコンテンツまでスキップ

データベースモデル

スタジオがデータをどこにどの形で保存しているかをまとめたドキュメントです。バックアップの範囲を決めたり、直接クエリを実行する必要があるときに参照します。

ストレージは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_logAI トークン使用量
スキーマschema_migrations適用されたマイグレーション名と実行時刻
watchers は過去には flows でした

2026-07-13 に名前を統一しました(ALTER TABLE flows RENAME TO watchers、データ保持)。 新規インストールも flows で作成した後、リネームする手順を踏みます — マイグレーション履歴は過去の記録であるため変更しないからです。直接クエリを書く場合は watchers です。

スキーマ変更はマイグレーションで管理されます​

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

-- 지금 어디까지 적용됐는지
SELECT name, applied_at FROM schema_migrations ORDER BY name;
スキーマを手動で変更しないでください

schema_migrations と実際のスキーマがズレると、次のアップグレード時にマイグレーションが 「既存のものを作ろうとする」エラーで失敗します。UI 全体が起動できなくなります。

アップグレード前は必ずバックアップを取ってください → バックアップと復旧。

ファイルシステム — DATA_ROOT​

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

格納内容ない場合
アプリワークスペース(生成されたソース)アプリを開けません — DB にはメタデータのみです
ビルド成果物再ビルドすればよいです
セッション・状態進行中の作業が失われます
バンドル PG データCOMPOSE_PROFILES=bundled-pg インストールでは DB 本体がここに있습니다
バンドル PG を使う場合、DATA_ROOT がすなわち DB バックアップです

バンドルモードでは PostgreSQL データディレクトリも DATA_ROOT 配下にあります。つまりこのパスを見落とすと DB とアプリソースを同時に 失います。

バックアップで見落としやすいもの​

取得すべきもの落とすと
PostgreSQL ダンプアカウント・ウォッチャー・会話・監査ログが失われる
DATA_ROOTアプリソースが失われ アプリを開けなくなる
/etc/kopens/plantpulse-studio.env接続情報・キーを再入力する必要がある
復旧を一度は実行してください

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

関連ドキュメント​