PostgreSQL 데이터 계층 추가

2026-04-29 15:22:54 +09:00
parent cbf5ed6c8c
commit 5ee6fcd54b
20 changed files with 429 additions and 34 deletions
--- a/docs/changelog.md
+++ b/docs/changelog.md
@@ -1,5 +1,12 @@
 # 업데이트 요약

+## v0.0.5
+
+- PostgreSQL 초기 스키마와 개발용 시드 데이터를 추가.
+- Nuxt 서버 API에 DB 저장소 계층을 추가.
+- DB 연결이 없을 때는 샘플 데이터로 동작하도록 fallback 구조를 추가.
+- Docker Compose에 PostgreSQL 서비스를 추가.
+
 ## v0.0.4

 - 헤더 좌측 아이콘을 사이드바 메뉴 토글 버튼으로 수정.
--- a/docs/deploy.md
+++ b/docs/deploy.md
@@ -34,6 +34,7 @@ npm install
 # 개발 환경 변수 설정
 cp .env.example .env.development
 # .env.development 파일에 개발 DB 연결 정보 입력
+# 로컬 DB 컨테이너를 호스트에서 접근할 때는 127.0.0.1:43119 사용

 # 개발 서버 실행 (127.0.0.1:43117)
 npm run dev
@@ -71,9 +72,10 @@ cd sori.studio
 # 운영 환경 변수 설정
 cp .env.example .env.production
 # .env.production 파일에 운영 DB 연결 정보와 APP_PORT=43118 입력
+# Docker 내부 앱에서 PostgreSQL에 접근할 때는 sori-studio-db:5432 사용

 # Docker 빌드 및 실행
-docker-compose up -d
+docker compose --env-file .env.production up -d
 ```

 ### 프로덕션 빌드 (NAS에서)
@@ -92,6 +94,7 @@ docker run -d -p 3000:3000 sori.studio:latest
 - 로컬 개발: 43117
 - NAS Docker 외부: 43118
 - 컨테이너 내부: 3000
+- PostgreSQL 외부: 43119
 - HTTPS: 3001 (SSL 설정 시)

 ---
@@ -100,9 +103,12 @@ docker run -d -p 3000:3000 sori.studio:latest

 - 로컬 개발: `.env.development`의 `DATABASE_URL`
 - NAS 운영: `.env.production`의 `DATABASE_URL`
+- 로컬 개발 예시: `postgres://sori_studio:비밀번호@127.0.0.1:43119/sori_studio`
+- NAS Docker 예시: `postgres://sori_studio:비밀번호@sori-studio-db:5432/sori_studio`
 - 개발 DB와 운영 DB는 반드시 별도 인스턴스 또는 별도 데이터베이스로 분리
 - 운영 DB는 로컬 개발 서버에서 직접 연결하지 않음
 - 관리 도구: CloudBeaver 등으로 추후 연결 가능하게 설계
+- NAS Docker 배포 시 PostgreSQL 초기 스키마는 `db/migrations/`의 SQL로 생성

 ## 사용자 액션 필요 항목

--- a/docs/history.md
+++ b/docs/history.md
@@ -1,5 +1,15 @@
 # 의사결정 이력

+## 2026-04-29 v0.0.5
+
+### PostgreSQL 기반 데이터 계층 결정
+
+DB 관리 도구로 CloudBeaver를 고려하고 NAS Docker 배포를 전제로 하기 때문에 초기 데이터베이스는 PostgreSQL로 잡는다. SQLite보다 운영/개발 분리, 외부 관리 도구 연결, 향후 확장에 유리하다.
+
+Nuxt 서버 API는 바로 DB에 강결합하지 않고 `server/repositories`를 통해 콘텐츠를 조회한다. `DATABASE_URL`이 설정된 환경에서는 PostgreSQL을 사용하고, 설정되지 않은 환경에서는 샘플 데이터를 사용해 화면과 API 개발을 계속할 수 있게 했다.
+
+Docker Compose에는 앱과 PostgreSQL 서비스를 함께 두되, 실제 운영 비밀번호와 연결 문자열은 `.env.production`에서 관리한다. DB 외부 포트는 기존 사용 포트와 겹치지 않도록 `43119`를 사용한다.
+
 ## 2026-04-29 v0.0.4

 ### 메뉴 토글 구현 방식 결정
--- a/docs/map.md
+++ b/docs/map.md
@@ -73,6 +73,15 @@
 | server/api/tags.get.js | 태그 목록 샘플 API |
 | server/utils/content-schema.js | Zod 콘텐츠 스키마 |
 | server/utils/sample-content.js | 샘플 콘텐츠 저장소 |
+| server/repositories/postgres-client.js | PostgreSQL 클라이언트 |
+| server/repositories/content-repository.js | 콘텐츠 조회 저장소 |
+
+## 데이터베이스
+
+| 파일 | 기능 |
+|------|------|
+| db/migrations/001_initial_schema.sql | PostgreSQL 초기 테이블 스키마 |
+| db/migrations/002_seed_development.sql | 개발용 샘플 데이터 |

 ## 설정/배포

--- a/docs/spec.md
+++ b/docs/spec.md
@@ -99,6 +99,7 @@ components/content/

 ### 환경 분리 원칙

+- 데이터베이스는 PostgreSQL을 기준으로 한다.
 - 로컬 개발 환경과 NAS 운영 환경은 서로 다른 DB를 사용
 - 로컬 개발 서버는 개발 DB만 연결
 - NAS 배포 환경은 운영 DB만 연결
@@ -114,7 +115,7 @@ components/content/
 | slug | String | URL 슬러그 |
 | content | Text | 마크다운 콘텐츠 |
 | excerpt | String | 요약 |
-| featured_image | String | 대표 이미지 |
+| featured_image | String nullable | 대표 이미지 |
 | status | Enum | published/draft/private |
 | published_at | DateTime | 발행일 |
 | created_at | DateTime | 생성일 |
@@ -128,7 +129,7 @@ components/content/
 | title | String | 제목 |
 | slug | String | URL 슬러그 |
 | content | Text | 마크다운 콘텐츠 |
-| featured_image | String | 대표 이미지 |
+| featured_image | String nullable | 대표 이미지 |
 | created_at | DateTime | 생성일 |
 | updated_at | DateTime | 수정일 |

@@ -140,6 +141,8 @@ components/content/
 | name | String | 태그명 |
 | slug | String | URL 슬러그 |
 | description | String | 설명 |
+| created_at | DateTime | 생성일 |
+| updated_at | DateTime | 수정일 |

 ### PostTags (다대다)

@@ -147,6 +150,7 @@ components/content/
 |------|------|------|
 | post_id | UUID | FK → Posts |
 | tag_id | UUID | FK → Tags |
+| created_at | DateTime | 생성일 |

 ---

@@ -159,6 +163,8 @@ components/content/
 - 별도 `backend/` 앱을 두지 않고 Nuxt/Nitro 서버 기능을 사용
 - 공개 API는 `server/api`에 작성
 - 서버 공통 스키마와 샘플 데이터는 `server/utils`에 작성
+- PostgreSQL 연결과 조회 로직은 `server/repositories`에 작성
+- `DATABASE_URL`이 없으면 샘플 데이터 저장소를 사용
 - 초기 단계에서는 같은 앱 배포로 관리 비용을 낮춤
 - 독립 API 서버가 필요해지는 시점에만 백엔드 분리를 재검토

@@ -203,8 +209,12 @@ components/content/

 ```env
 # Database
-DATABASE_URL=
-DATABASE_NAME=
+DATABASE_URL=postgres://sori_studio:change-this-password@sori-studio-db:5432/sori_studio
+DATABASE_NAME=sori_studio
+POSTGRES_DB=sori_studio
+POSTGRES_USER=sori_studio
+POSTGRES_PASSWORD=change-this-password
+DB_PORT=43119

 # Auth
 ADMIN_EMAIL=
@@ -237,11 +247,12 @@ APP_PORT=43118
 | 로컬 개발 서버 | 43117 |
 | NAS Docker 외부 포트 | 43118 |
 | 컨테이너 내부 포트 | 3000 |
+| PostgreSQL 외부 포트 | 43119 |

 ---

 ## 버전 관리

- 현재 버전: v0.0.4
+- 현재 버전: v0.0.5
 - 첫 커밋 이후 변경사항을 커밋할 때마다 패치 버전 증가
 - 메이저/마이너 버전은 구조 변경 또는 기능 묶음 단위로 결정
--- a/docs/todo.md
+++ b/docs/todo.md
@@ -51,17 +51,15 @@

 ## 데이터베이스

- [ ] Posts 테이블 설계
- [ ] Pages 테이블 설계
- [ ] Tags 테이블 설계
- [ ] PostTags 테이블 설계
- [ ] 로컬 개발 DB 연결 설정 작성
- [ ] NAS 운영 DB 연결 설정 작성
+- [ ] PostgreSQL 마이그레이션 실행 스크립트 작성
+- [ ] 로컬 개발 DB 컨테이너 실행 가이드 작성
+- [ ] NAS 운영 DB 연결 설정 실제 값 작성
 - [ ] 개발 DB와 운영 DB 분리 검증 절차 작성
- [ ] CloudBeaver 등 DB 관리 도구 연결 방식 결정
+- [ ] CloudBeaver PostgreSQL 연결 방식 확정

 ## 배포

 - [ ] UGREEN NAS Docker 배포 가이드 작성
 - [ ] Docker 빌드 검증
+- [ ] `.env.production` 작성 후 `docker compose --env-file .env.production config` 검증
 - [ ] NAS 운영 환경 변수 작성
--- a/docs/update.md
+++ b/docs/update.md
@@ -1,5 +1,14 @@
 # 업데이트 이력

+## v0.0.5
+
+- PostgreSQL 초기 스키마 마이그레이션 추가.
+- 개발용 시드 데이터 SQL 추가.
+- Nuxt 서버 API 저장소 계층 추가.
+- `DATABASE_URL`이 있으면 PostgreSQL을 사용하고, 없으면 샘플 데이터를 사용하도록 수정.
+- Docker Compose에 PostgreSQL 서비스와 전용 DB 포트 43119 추가.
+- 공개 API가 저장소 계층을 통해 게시물, 페이지, 태그를 조회하도록 수정.
+
 ## v0.0.4

 - 헤더 좌측 아이콘을 브랜드 마크에서 메뉴 토글 버튼으로 수정.