본문으로 건너뛰기

데이터베이스 모델

스튜디오가 데이터를 어디에 무슨 모양으로 담는지 정리한 문서입니다. 백업 범위를 정하거나 직접 조회해야 할 때 봅니다.

저장소가 둘입니다

PostgreSQL 에 메타데이터가 들어가고, 파일 시스템(DATA_ROOT)에 앱 소스와 빌드 산출물이 들어갑니다. 둘 다 받아야 복구됩니다 — DB 만 받으면 앱 코드가 없고, 파일만 받으면 누가 무엇을 만들었는지가 없습니다.

저장소담는 것
PostgreSQL사용자·앱 메타·대화·감사·와처·스킬
파일 시스템 (DATA_ROOT)워크스페이스(앱 소스) · 빌드 산출물 · 상태

PostgreSQL 은 두 모드 중 하나입니다 — 번들 컨테이너(기본) 또는 플랫폼 공용 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 와 실제 스키마가 어긋나면, 다음 업그레이드에서 마이그레이션이 「이미 있는 것을 만들려다」 실패합니다. 화면 기동이 통째로 막힙니다.

업그레이드 전에는 백업을 먼저 받으세요 → 백업과 복구.

파일 시스템 — 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접속 정보·키를 다시 채워 넣어야 한다
복구를 한 번은 해 보세요

백업만 있고 복구를 해 본 적이 없는 상태가 가장 위험합니다. 절차는 백업과 복구 에 있습니다.

관련 문서​