서비스의 지속 가능한 성장을 위해 데이터베이스 인프라를 이전하거나 리팩토링하는 작업은 언제나 높은 리스크를 수반한다. 특히 단 1초의 서비스 중단이나 한 건의 데이터 유실도 허용되지 않는 엔터프라이즈 환경에서는 정교한 격리 전략과 검증 시스템이 필수적이다.

최근 진행된 ‘translation-manager’ 프로젝트의 18번째 스프린트에서는 레거시 Supabase 환경에서 SQLite 프로바이더로의 안전한 전환을 위해 ‘Pilot Migration 시스템’을 완전히 마스터 브랜치에 안착시키고, 빌드 및 타입 에러 0개의 완벽한 프로덕션 배포 준비 상태를 달성하였다.

이 과정에서 사용된 4단계 데이터 전환 메커니즘, Feature Flag 기반 인프라 제어, 그리고 개발 생산성을 극대화한 설정 병렬 처리 전략을 상세히 공유한다.

1. 안정적인 인프라 이전을 위한 4단계 마이그레이션 추상화 설계

시스템을 일시에 갈아끼우는 빅뱅 방식의 위험성을 배제하기 위해, 백엔드 코어 단에 프로바이더 패턴(Provider Pattern)과 레포지토리 패턴(Repository Pattern)을 도입하여 레거시 인프라와 신규 인프라가 독립적으로 연동될 수 있는 추상화 뼈대를 구축하였음. 이를 기반으로 다음과 같은 4단계 점진적 롤아웃 아키텍처를 구현하였음.

1. Shadow Mode (무증상 실행): 모든 쓰기(Write) 작업을 기존 레거시와 신규 프로바이더에 병렬로 쏘아주되, 백그라운드에서 양측의 결과 데이터를 정밀 비교하고 사용자에게는 레거시의 결과만 안전하게 반환함.

2. Dark Launch (병렬 실행): 읽기(Read) 작업을 두 인프라에서 병렬로 호출하여 원본 데이터와의 정합성 및 성능 지표를 검증하되, 화면 렌더링은 레거시 데이터를 즉시 사용하여 속도 저하를 방지함.

3. Dual Write (양쪽 쓰기): 두 데이터베이스에 동시에 쓰기 작업을 수행하되, 신규 프로바이더에서 예외 에러가 발생하면 비상 복구 큐(Recovery Queue)에 데이터를 적재하고 경보를 울려 데이터 유실을 완전 차단함.

4. Full Cutover (완전 전환): 신규 SQLite 프로바이더만을 최종 진실의 소스(Source of Truth)로 전격 사용하며, 예상치 못한 크래시 발생 시에만 레거시로 자동 폴백(Fallback)되도록 차단벽을 형성함.

2. 10대 핵심 Feature Flag 엔지니어링 및 우선순위 알고리즘

코드의 수정이나 재배포 절차 없이 배포 환경에서 시스템의 데이터 흐름을 실시간으로 통제하기 위해 10개의 제어 플래그를 정립하고 관리용 Admin API를 연동하였음

플래그 설계: USE_SQLITE_REPOSITORY, SQLITE_DUAL_WRITE_MODE, SQLITE_SHADOW_MODE 등을 촘촘히 선언하여 각 도메인별(사용자 관리, 플랫폼 API 등) Pilot 모드를 세부 통제할 수 있도록 함.

계층형 인터셉터 우선순위: 환경 변수, Admin API, 기본값 간의 설정 충돌을 방지하기 위해 시스템 내부적으로 FULL_CUTOVER > DUAL_WRITE > SHADOW_MODE > DARK_LAUNCH 순의 엄격한 런타임 실행 우선순위 연산 장치를 설계하였음.

3. 고속 공정 관리를 위한 환경 설정 및 테스트 코드 병렬 처리 전략

대규모 아키텍처 개편 후 남은 과제는 시스템 안전장치인 ‘pre-commit hook 설정’과 32개의 실패 레이어를 수정하는 ‘PILOT-TEST-001’ 검증 작업이었음. 이를 순차적으로 진행할 경우 발생하는 시간적 병목을 해결하기 위해 독립 공정 병렬 시나리오를 전격 적용하였음.

ㄱ. 의존성 제로 환경 분리를 통한 1.5시간의 공정 단축

독립성 검증: pre-commit hook 설정은 .husky 및 package.json 등의 환경 설정 파일만 다루므로 기존 소스 코드에 영향이 없고, PILOT-TEST-001은 tests/ 디렉토리 내의 파일들만 정밀 수정하므로 상호 간의 소스 충돌 가능성이 0%에 수렴하였음.

병렬 가속: 이를 순차 처리했다면 8시간(30분 + 7.5시간)이 소요되었을 공정을, max(30분, 7.5시간) 구조의 분할 병렬 처리 전략을 통해 최종 7.5시간으로 압축하며 총 1.5시간의 귀중한 개발 리소스를 정량적으로 절약하였음.

4. Husky와 lint-staged 연동을 통한 방어적 가드레일 구축

개발자의 단순 실수나 불완전한 코드가 원격 리포지토리에 커밋되어 CI/CD 배포 파이프라인을 오염시키는 문제를 원천 차단하기 위해 pre-commit 단계의 자동화 체크 가드레일을 장착하였음.

.husky/pre-commit 스크립트를 통해 개발자가 커밋 명령어를 입력하는 즉시 백그라운드에서 npx tsc --noEmit 정적 타입 체크가 강제 구동되도록 설계하였음.

타입 컴파일 오류가 단 한 건이라도 발견되면 그 즉시 로컬 커밋 프로세스를 중단(Exit 1)시키며, 통과된 안전한 파일들만 lint-staged를 타고 ESLint 및 Prettier 포맷팅을 거쳐 깔끔한 상태로 커밋되도록 제어권을 자동화하였음.

5. 기술적 부채 청산 및 99.8% 테스트 패스 레이트 달성

스프린트 후반부에는 19개의 복잡한 정적 타입 오류를 전수 교정하는 하드코어 디버깅을 전개하였음. Next.js 15 업그레이드로 인해 비동기 Promise 객체 구조로 변경된 라우트 핸들러의 context.params 인자 타입을 await context.params 코드로 전면 수정한 것이 대표적임.

더불어 sqlite.test.ts, shadow-mode.test.ts 등에서 깨져 있던 32개의 테스트 명세를 정교하게 가공하여, 최종적으로 548개 테스트 파일 통과 및 99.8%의 경이로운 패스 레이트(Pass Rate)를 확보하는 데 성공하였음.

10시간의 초집중 스프린트를 통해 총 22개의 클린 마이크로 커밋이 안전하게 Git 리포지토리에 합류하였음.
피널 마이그레이션 가이드, 안전 운영 가이드, 롤백 플레이북 등 엔터프라이즈 레벨의 15종 표준 작업 절차서(SOP) 문서까지 완비되어 팀 전체의 아키텍처 싱크를 맞추었음.

당장 다가오는 오픈 당일에는 안전한 1단계 Shadow Mode를 즉시 활성화하여 3일간 정합성 지표를 모니터링할 예정임. 이어서 순차적으로 Dark Launch, Dual Write 단계를 밟아 최종적으로 2주 뒤 무중단 Full Cutover를 완수하는 인프라 이전을 이룩할 것임.