데이터베이스 모델

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

저장소가 둘입니다

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_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`	접속 정보·키를 다시 채워 넣어야 한다

복구를 한 번은 해 보세요

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