Cloudflare Workers D1 로컬 개발에서 프로덕션까지 — 마이그레이션·시드·배포 자동화 한 줄로

D1을 Workers에 올릴 때 가장 많이 삽질하는 구간은 로컬과 프로덕션의 스키마 동기화다. wrangler dev로 로컬 D1을 띄워도, 마이그레이션 파일이 없으면 d1 execute로 직접 쿼리를 날려야 하고, 타입은 또 따로 뽑아야 한다. 이걸 한 번에 도는 스크립트를 짜고 나서야 배포 전 드리프트가 사라졌다.

사실: 로컬 D1은 메모리 DB, 프로덕션은 영구 저장소

wrangler dev --local을 켜면 .wrangler/state/v3/d1 아래 SQLite 파일이 생긴다. 그런데 이 파일은 마이그레이션을 적용하지 않으면 빈 스키마다. 문서에는 wrangler d1 migrations create → wrangler d1 migrations apply 순서를 권장하지만, 로컬에서 apply를 까먹고 코드만 고치면 타입이 안 맞는다. 프로덕션에선 wrangler deploy 시 자동 적용되지만, 로컬은 수동이다.

이유: 마이그레이션·시드·타입 생성을 따로 돌리니 누락이 생긴다

기존 흐름:

wrangler d1 migrations create — 파일 생성
SQL 작성
wrangler d1 migrations apply --local — 로컬 적용
wrangler d1 migrations apply --remote — 프로덕션 적용
wrangler types — TypeScript 타입 생성
시드 데이터는 별도 스크립트로 INSERT 수행

3번을 까먹으면 로컬 타입이 낡고, 5번을 안 돌리면 컴파일 에러가 나지 않아 런타임에 터진다. 6번은 테스트 데이터가 필요할 때마다 손으로 돌려야 했다.

평가: 한 명령으로 다 도는 파이프라인 구성

package.json에 db:reset 스크립트를 넣고, 로컬 개발 시 npm run db:reset && wrangler dev만 치면 되게 했다.

{
  "scripts": {
    "db:reset": "wrangler d1 migrations apply --local --yes && wrangler types && npm run db:seed",
    "db:seed": "node scripts/seed.mjs",
    "db:migrate": "wrangler d1 migrations create && wrangler d1 migrations apply --local --yes && wrangler types"
  }
}

scripts/seed.mjs는 wrangler d1 execute --local --command="..."로 초기 데이터를 넣는다. 마이그레이션 파일이 생기면 자동으로 --local 적용 → 타입 재생성 → 시드까지 한 번에 돈다.

프로덕션 배포 전에는 wrangler d1 migrations apply --remote만 따로 친다. --yes 플래그로 대화형 프롬프트를 건너뛰면 CI에서도 쓸 수 있다.

부연: 스키마 드리프트 감지와 롤백

wrangler d1 migrations list로 로컬·원격 적용 상태를 비교한다. applied_at이 다른 마이그레이션이 있으면 배포 중단.
롤백은 wrangler d1 execute --remote --command="DROP TABLE ..."로 수동 처리. D1은 DOWN 마이그레이션을 공식 지원하지 않으므로, 역방향 SQL을 별도 파일로 관리한다.
시드 스크립트는 INSERT OR IGNORE를 써서 멱등성을 보장한다. 테스트용 데이터만 넣고, 실제 사용자 데이터는 건드리지 않는다.

이 구조로 바꾼 뒤로는 “로컬에선 되는데 프로덕션에서 컬럼 없다”는 에러가 0건이 됐다. 마이그레이션 파일이 곧 스키마 진실이 되니, 코드 리뷰 시 SQL diff만 보면 된다.

출처

내부 실측: wrangler d1 migrations apply --local --yes && wrangler types 파이프라인 구성 및 검증 (2026-08-04)
Cloudflare D1 문서 — 마이그레이션 — 열람: 2026-08-04
Notion 시드: «Cloudflare Workers D1 로컬 개발 워크플로» — 공개 가능한 요지만