Skip to Content
DecisionsADR-0014: Neon 마이그레이션을 Vercel prebuild에서 전용 GitHub Actions로 분리한다

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 권한 부족 → database owner_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