ADR-0014: Neon 마이그레이션을 Vercel prebuild에서 전용 GitHub Actions로 분리한다
- Status: Accepted
- Date: 2026-09-21
- 관련: HMH-9438 (이번 작업 — 롤아웃 2단계) · HMH-9379 (1단계 — 전용 워크플로 추가, PR #5989) · HMH-9421 (apply 시크릿 이름 수정) · HMH-9435 (dry-run URI/권한 수정) · HMH-8566 (비멱등 마이그레이션이 prod 릴리즈를 하드블록한 이력) · HMH-8695 (apps/app sunset)
Context
prod 마이그레이션이 apps/app(+short-link) Vercel 빌드의 prebuild(db:migrate:conditional, ENABLE_MIGRATION=true)에서 실행돼 왔다. 이는 과거 apps/app이 유일한 빌드-타임 Neon 리더였던 시절의 결합이다.
그 전제가 소멸했다:
- 네이티브 전환으로 apps/app의 DB 코드가 사라졌다(지금은 package.json 의존성 선언만 남음). apps/app은 sunset 경로(HMH-8695)라, 감축 대상 앱에 prod 마이그레이터가 얹혀 있는 구조 자체가 취약하다.
- 나머지 소비자(apps/api·dashboard·short-link)는 전부 런타임 리더라 빌드-타임 마이그레이션과 결합될 이유가 없다.
- 비멱등 마이그레이션이 prod 릴리즈를 하드블록한 이력이 있다(HMH-8566:
IF NOT EXISTS없는ADD COLUMN이 prod 기존 상태와 충돌해 develop→main 빌드가 죽음).
ENABLE_MIGRATION은 Vercel 프로젝트 env로 주입된다(prod=true, develop-preview=true, 나머지 preview=false). 즉 지금은 Vercel 빌드가 prod/develop 두 DB를 마이그레이트하고 있고, 이는 새 전용 워크플로의 두 타깃(main→prod / develop→develop)과 정확히 대응된다.
PR#1(HMH-9379)에서 전용 워크플로 2종을 추가하되 prebuild는 안전망으로 유지했다. 이후 두 게이트를 workflow_dispatch로 실증 검증했고, 그 과정에서 세 개의 배선 버그를 프로덕션 전에 잡았다:
- apply: develop 시크릿 이름 불일치(
DEVELOP_DATABASE_URL→DEV_DATABASE_URL, HMH-9421) - dry-run: create 응답
connection_uri부재 → 전용 엔드포인트로 확보 / 임의 role 권한 부족 → databaseowner_name사용 / query 인코딩(HMH-9435)
두 게이트 모두 prod 데이터로 green을 확인한 뒤, 이 PR(#2)에서 구경로(prebuild)를 제거한다.
검토한 대안
| 대안 | 채택 안 한 이유 |
|---|---|
| A. prebuild 유지(현상) | apps/app sunset에 prod 마이그레이터가 얹혀 있는 취약 구조 지속. 빌드-타임 결합이라 마이그레이션과 앱 배포가 한 실패 지점에 묶임(HMH-8566 재발 표면). |
| B. prebuild + 전용 워크플로 병존 | 같은 마이그레이션을 두 경로가 중복 실행(멱등이라 무해하나) — 실패 지점·관측 지점이 둘로 갈려 오히려 진단이 흐려진다. 병존은 PR#1의 관찰용 임시 상태였고 목적을 다했다. |
| C. 순서 보장(마이그레이션 완료 후 빌드) 파이프라인 구축 | 크로스앱 빌드 순서는 오늘도 보장되지 않는다. 순서에 기대는 대신 expand-first(하위호환) 마이그레이션을 안전모델로 삼으면 순서 보장 인프라가 불필요하다. |
Decision
prebuild의 마이그레이션 호출을 제거하고 전용 GitHub Actions 단일 경로로 일원화한다.
apps/app/package.json:prebuild를yarn syncpack만 남긴다(⚠️syncpack은 dashboard 빌드 게이트라 유지).db:migrate·db:migrate:conditional스크립트 제거.apps/short-link/package.json:prebuild(마이그레이션 전용) 라인과db:migrate·db:migrate:conditional제거.turbo.json: build env 허용목록에서ENABLE_MIGRATION제거(더 이상 읽는 스크립트가 없어 사문).- 실행 경로는
.github/workflows/db-migrate.yml(apply: main→prod / develop→develop) +.github/workflows/db-migrate-check.yml(PR dry-run 게이트) +packages/db/scripts/ci-dry-run-migrate.sh.
안전모델은 배포 순서가 아니라 expand-first(하위호환) 마이그레이션이다. dry-run 게이트가 prod를 copy-on-write 포크해 미리 적용해 봄으로써 HMH-8566류를 PR 단계에서 차단한다.
Consequences
좋아지는 것
- prod 마이그레이터가 sunset 앱(apps/app)에서 분리돼, 앱 감축이 마이그레이션을 깨지 않는다.
- 마이그레이션 실패 지점·관측 지점이 GitHub Actions 한 곳으로 모인다(Vercel 빌드 로그에 섞이지 않음).
- PR dry-run 게이트로 비멱등 마이그레이션을 머지 전에 잡는다(HMH-8566류 재발 방지).
감수하는 것
- 마이그레이션 실행이 Vercel 빌드와 분리되어, “앱 빌드 전에 스키마가 반드시 적용됨”이라는 빌드-타임 보장이 사라진다. 대신 expand-first를 규율로 지켜야 한다(하위호환이면 적용/배포 순서가 무관).
- Vercel 프로젝트 env의
ENABLE_MIGRATION제거는 수동 후속 작업이다(코드로는 무력화되지만 설정값은 남음).
이 결정을 다시 열어야 할 때
- expand-first로 표현 불가능한 파괴적 마이그레이션이 잦아져 순서 보장이 실제로 필요해지면, 대안 C(마이그레이션→배포 순서 파이프라인)를 재검토한다.
- 빌드-타임에 최신 스키마가 반드시 필요한 새 빌드-타임 Neon 리더가 생기면(현재 없음), 그 앱에 한해 게이팅을 재도입할지 검토한다.
Last updated on