Database Model
This document organizes where the Studio stores data and in what format. Refer to it when setting backup scopes or querying directly.
Metadata is stored in PostgreSQL, and app source and build artifacts are stored in the file system(DATA_ROOT). Both are required for a complete recovery — the DB alone has no app code, and files alone lack information about who created what.
| Storage | Contents |
|---|---|
| PostgreSQL | Users · App metadata · Conversations · Audit logs · Watchers · Skills |
File System (DATA_ROOT) | Workspaces (app source) · Build artifacts · State |
PostgreSQL operates in one of two modes — bundled container (default) or platform-shared PG. See the Environment Variable Reference.
Tables — 11 of them
| Group | Table | Contents |
|---|---|---|
| Users | studio_users | Accounts · Roles (admin/builder/viewer) · Password hashes |
studio_tokens | Issued tokens | |
| Conversations | ask_conversations | Chat threads |
ask_history | Exchanged messages and elapsed time | |
| Watchers | watchers | Periodic monitoring definitions and notification settings |
notification_seen | Notification acknowledgment status | |
| Skills | skills | Registered field expertise |
| Deployment | deploy_log | Deployment history |
| Audit & Usage | audit_log | Who did what |
usage_log | AI token usage | |
| Schema | schema_migrations | Applied migration names and timestamps |
flows appears in the migration logNew installations follow a sequence of creating with flows and then renaming to watchers — because migration history is immutable once written. If you query directly, look at watchers.
Schema changes are managed by migrations
On server startup, the .sql of src/infra/db/migrations/ are applied in numerical order, and applied file names are recorded in schema_migrations. Already applied ones are not re-run.
-- 지금 어디까지 적용됐는지
SELECT name, applied_at FROM schema_migrations ORDER BY name;
If schema_migrations and the actual schema diverge, the next upgrade will fail when a migration tries to create something that already exists. This will block the entire UI startup.
Before an upgrade, take a backup first → Backup and Restore.
File System — DATA_ROOT
The default is /var/lib/pp-studio. Everything below is contained within it.
| Contents | If Missing |
|---|---|
| App workspace (generated source) | Cannot open apps — the DB only contains metadata |
| Build artifacts | Can be rebuilt |
| Sessions · State | Ongoing work is lost |
DATA_ROOTThe Studio uses an external PostgreSQL. Even if you back up DATA_ROOT entirely, the DB must be backed up separately — see Backup and Restore.
Things easily missed in backups
| What to Back Up | If Missed |
|---|---|
| PostgreSQL dump | Accounts · Watchers · Conversations · Audit records are lost |
DATA_ROOT | App source is lost, so apps cannot be opened |
/etc/kopens/plantpulse-studio.env | Connection info and keys must be re-entered |
The most dangerous state is having a backup without ever having practiced a restore. The procedure is in Backup and Restore.
Related Documents
- Backup and Restore
- Environment Variable Reference — DB modes and
DATA_ROOT - Password · API Key Change — AI key rotation (DB connection is
DATABASE_URL) - Initial Password Change — Bootstrap admin account