DB 마이그레이션
모든 명령은 api/ 디렉토리에서 실행한다.
워크플로우
1단계: 현재 상태 확인 (항상 먼저 실행)
어떤 작업이든 시작 전에 현재 마이그레이션 상태를 확인한다.
cd api && bun run db:status-dev사용자에게 적용된 마이그레이션 목록과 미적용 마이그레이션을 보여준다.
2단계: 의도에 따라 분기
상태 확인만 요청한 경우
→ 1단계 결과를 보여주고 종료.
마이그레이션 실행 (up)
cd api && bun run db:up-dev- dbmate 마이그레이션 실행 후
extract-schema가 자동 실행된다. - 스키마 파일(
db/schema/)이 자동 갱신된다. - 결과를 보여주고, 변경된 스키마 파일 목록을 안내한다.
마이그레이션 롤백 (down)
cd api && bun run db:down-dev- 실행 전 반드시: 롤백 대상 마이그레이션 파일명을 보여주고, 사용자 승인을 받은 후 실행한다.
- 가장 최근 마이그레이션 1건만 롤백된다.
- 롤백 후
extract-schema가 자동 실행된다.
새 마이그레이션 생성
cd api && bun run db:new {migration_name}db/migrations/YYYYMMDDHHMMSS_{migration_name}.sql파일이 생성된다.- 생성된 파일을 열고, 아래 템플릿 구조를 안내한다:
-- migrate:up
-- migrate:down3단계: 결과 보고
실행 결과를 요약하고, 오류 발생 시 원인을 분석한다.
파일 위치
| 경로 | 용도 |
|---|---|
api/db/migrations/ | 마이그레이션 파일 |
api/db/schema/ | 추출된 스키마 파일 |
api/db/dev.env | DB 연결 정보 |
오류 대응
| 증상 | 원인 | 해결 |
|---|---|---|
| 연결 실패 | DATABASE_URL 오류 또는 DB 서버 다운 | api/db/dev.env 확인, DB 서버 상태 점검 |
| already applied | 마이그레이션이 이미 적용됨 | db:status-dev로 현재 상태 확인 후 안내 |
| SQL syntax error | 마이그레이션 파일 문법 오류 | 오류 메시지의 라인/컬럼 정보로 파일 수정 |
| index already exists | 중복 인덱스 생성 시도 | CREATE INDEX IF NOT EXISTS로 변경 또는 기존 인덱스 확인 |