Back to Details

peach-db-migrate

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

DB 마이그레이션

DB迁移

모든 명령은 
api/
디렉토리에서 실행한다.
所有命令都在 
api/
目录下执行。

워크플로우

工作流

1단계: 현재 상태 확인 (항상 먼저 실행)

1步：检查当前状态（始终优先执行）

어떤 작업이든 시작 전에 현재 마이그레이션 상태를 확인한다.
bash
cd api && bun run db:status-dev
사용자에게 적용된 마이그레이션 목록과 미적용 마이그레이션을 보여준다.
无论开始任何操作，都需要先确认当前的迁移状态。
bash
cd api && bun run db:status-dev
向用户展示已应用的迁移列表和未应用的迁移。

2단계: 의도에 따라 분기

第二步：根据用户意图分支处理

상태 확인만 요청한 경우

仅请求状态检查的情况

→ 1단계 결과를 보여주고 종료.
→ 展示第一步的结果后结束流程。

마이그레이션 실행 (up)

执行迁移（up）

bash
cd api && bun run db:up-dev
  • dbmate 마이그레이션 실행 후 
    extract-schema
    가 자동 실행된다.
  • 스키마 파일(
    db/schema/
    )이 자동 갱신된다.
  • 결과를 보여주고, 변경된 스키마 파일 목록을 안내한다.
bash
cd api && bun run db:up-dev
  • 执行dbmate迁移后会自动运行
    extract-schema
  • Schema文件(
    db/schema/
    )会自动更新
  • 展示执行结果，并告知变更的Schema文件列表。

마이그레이션 롤백 (down)

迁移回滚（down）

bash
cd api && bun run db:down-dev
  • 실행 전 반드시: 롤백 대상 마이그레이션 파일명을 보여주고, 사용자 승인을 받은 후 실행한다.
  • 가장 최근 마이그레이션 1건만 롤백된다.
  • 롤백 후 
    extract-schema
    가 자동 실행된다.
bash
cd api && bun run db:down-dev
  • 执行前必须操作：先展示待回滚的迁移文件名，获得用户批准后再执行
  • 仅回滚最近1条迁移记录
  • 回滚完成后会自动运行
    extract-schema

새 마이그레이션 생성

创建新迁移

bash
cd api && bun run db:new {migration_name}
  • db/migrations/YYYYMMDDHHMMSS_{migration_name}.sql
    파일이 생성된다.
  • 생성된 파일을 열고, 아래 템플릿 구조를 안내한다:
sql
-- migrate:up


-- migrate:down
bash
cd api && bun run db:new {migration_name}
  • 会生成
    db/migrations/YYYYMMDDHHMMSS_{migration_name}.sql
    文件
  • 打开生成的文件，提供如下模板结构参考：
sql
-- migrate:up


-- migrate:down

3단계: 결과 보고

第三步：结果报告

실행 결과를 요약하고, 오류 발생 시 원인을 분석한다.
总结执行结果，若出现错误则分析原因。

파일 위치

文件位置

경로용도
api/db/migrations/
마이그레이션 파일
api/db/schema/
추출된 스키마 파일
api/db/dev.env
DB 연결 정보
路径用途
api/db/migrations/
迁移文件
api/db/schema/
提取的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
로 변경 또는 기존 인덱스 확인
症状原因解决方案
连接失败DATABASE_URL配置错误或DB服务宕机检查
api/db/dev.env
配置，确认DB服务运行状态
already applied迁移已被应用执行
db:status-dev
查看当前状态后告知用户
SQL syntax error迁移文件存在语法错误根据错误信息提供的行/列位置修改对应文件
index already exists尝试创建重复索引修改为
CREATE INDEX IF NOT EXISTS
语法或检查现有索引