From 034bcf9bc77ec499d2f1861dad7586ec4e62bbc0 Mon Sep 17 00:00:00 2001 From: ttipo Date: Mon, 22 Jun 2026 01:59:31 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20command.md=20=EC=97=90=20DB=20=EB=A7=88?= =?UTF-8?q?=EC=9D=B4=EA=B7=B8=EB=A0=88=EC=9D=B4=EC=85=98=20=EB=AA=85?= =?UTF-8?q?=EB=A0=B9=EC=96=B4=20=EA=B0=80=EC=9D=B4=EB=93=9C=20=EC=B6=94?= =?UTF-8?q?=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 동작 방식(dev synchronize / 운영 migrationsRun 자동), 스크립트(generate/create/ run/revert), 새 마이그레이션 생성 절차(임시 DB diff), 기존 운영 DB 베이스라인 SQL 정리. Co-Authored-By: Claude Opus 4.8 (1M context) --- command.md | 78 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 78 insertions(+) diff --git a/command.md b/command.md index 9bbbaf8..ae467e5 100644 --- a/command.md +++ b/command.md @@ -27,6 +27,84 @@ sudo docker compose --env-file .env.production up -d --build sudo docker compose --env-file .env.production logs -f backend ``` +## 데이터베이스 마이그레이션 (TypeORM) + +> 스키마 변경은 **마이그레이션**으로 관리한다. (SSOT: `backend/src/migrations/`, CLI 설정: `backend/src/data-source.ts`) + +### 동작 방식 + +| 환경 | 동작 | +| ---- | ---- | +| 개발 | `synchronize: true` — 엔티티 변경이 DB에 **자동 반영**(마이그레이션 불필요) | +| 운영 | `synchronize: false` + `migrationsRun: true` — 컨테이너 **기동(부팅) 시** `dist/migrations` 의 미적용 마이그레이션을 **자동 실행** | + +- **빌드만으로는 실행되지 않는다.** `up`(기동)해야 적용된다. 이미 적용된 마이그레이션은 `migrations` 테이블 기록으로 건너뛴다(멱등). +- 운영 배포(`sudo docker compose --env-file .env.production up -d --build`)는 빌드 시 마이그레이션을 이미지에 포함 → 기동 시 자동 적용 → **빈 운영 DB에 스키마가 자동 생성**된다. 별도 명령 불필요. +- ⚠️ **전제: 운영 DB가 비어 있어야 한다.** 이미 테이블이 있으면 `already exists` 로 부팅이 실패한다. (데이터 없으면 DB 재생성 후 배포, 데이터 보존이 필요하면 아래 *베이스라인* 참조) + +### 스크립트 (backend/ 에서 실행 — DB 접속 env 필요) + +```bash +cd backend +npm run migration:generate -- ./src/migrations/<이름> # 엔티티 변경분으로 새 마이그레이션 생성 +npm run migration:create -- ./src/migrations/<이름> # 빈 마이그레이션 파일(수동 SQL 작성용) +npm run migration:run # 미적용 마이그레이션 실행 +npm run migration:revert # 마지막 마이그레이션 1건 되돌리기 +``` + +DB 접속값은 환경변수로 주입한다. 로컬에서는 dev DB가 호스트에 노출되어 있으므로(`DB_PORT`, `.env.development`) 그대로 사용: + +```bash +# Linux/macOS (bash) +DB_HOST=localhost DB_PORT= DB_USER= DB_PASSWORD= DB_NAME= npm run migration:run +``` + +```powershell +# Windows PowerShell +$env:DB_HOST='localhost'; $env:DB_PORT=''; $env:DB_USER=''; $env:DB_PASSWORD=''; $env:DB_NAME=''; npm run migration:run +``` + +### 새 마이그레이션 만들기 (스키마 변경 시) + +개발 DB는 `synchronize` 로 이미 최신 엔티티 상태라 **dev DB를 직접 diff 하면 변경분이 안 잡힌다.** +"기존 마이그레이션까지 적용된 임시 DB" 대비 차이만 추출한다(실 데이터 무손상): + +```bash +DB=comrelay-db # DB 컨테이너명, USER= + +# 1) 임시 빈 DB 생성 +docker exec $DB psql -U -d -c "CREATE DATABASE comrelay_miggen OWNER ;" + +# 2) 임시 DB에 기존 마이그레이션 적용(= 변경 전 기준 스키마) +DB_HOST=localhost DB_PORT= DB_USER= DB_PASSWORD= DB_NAME=comrelay_miggen npm run migration:run + +# 3) 엔티티 변경분만 새 마이그레이션으로 추출 +DB_HOST=localhost DB_PORT= DB_USER= DB_PASSWORD= DB_NAME=comrelay_miggen npm run migration:generate -- ./src/migrations/<이름> + +# 4) 생성된 파일 리뷰 후 임시 DB 삭제 +docker exec $DB psql -U -d -c "DROP DATABASE comrelay_miggen;" +``` + +생성된 마이그레이션을 커밋·푸시하면 다음 운영 배포의 기동 시 자동 적용된다. + +### 기존 운영 DB 베이스라인 (이미 스키마가 있고 데이터 보존이 필요할 때) + +운영 DB가 이미 동일 스키마를 갖고 있다면, 초기 마이그레이션을 "이미 적용됨"으로 기록해 재실행(=충돌)을 막는다. + +```sql +-- migrations 추적 테이블이 없으면 생성(최초 1회) +CREATE TABLE IF NOT EXISTS "migrations" ( + "id" SERIAL PRIMARY KEY, + "timestamp" bigint NOT NULL, + "name" character varying NOT NULL +); +-- 초기 마이그레이션을 적용 완료로 표시(파일명의 타임스탬프·클래스명과 일치시킬 것) +INSERT INTO "migrations" ("timestamp", "name") +VALUES (1782060613058, 'CreateInitialSchema1782060613058'); +``` + +이후 `up` 하면 기록된 마이그레이션은 건너뛰고, 이후 추가된 마이그레이션만 적용된다. + ## 외부 노출 (선택) ```bash