무중단(제로 다운타임) 스키마 변경: 안전하게 유지되는 추가적 마이그레이션

스키마 변경에서 무중단(제로 다운타임)이 실제로 의미하는 것

무중단 스키마 변경은 아무 것도 바꾸지 않는다는 뜻이 아닙니다. 사용자들이 데이터베이스와 앱을 업데이트하는 동안 실패나 작업 중단 없이 계속 작업할 수 있게 한다는 뜻입니다.

다운타임은 시스템이 정상적으로 동작하지 않는 모든 순간입니다. 500 에러, API 타임아웃, 빈 화면이나 잘못된 값이 표시되는 화면, 백그라운드 작업 실패, 또는 긴 마이그레이션이 잠금으로 인해 읽기는 되지만 쓰기를 막는 데이터베이스 등이 모두 여기에 해당합니다.

스키마 변경은 주 UI 외에도 여러 곳을 깨뜨릴 수 있습니다. 흔한 실패 지점으로는 오래된 응답 형식을 기대하는 API 클라이언트, 특정 컬럼을 읽거나 쓰는 백그라운드 작업, 테이블을 직접 조회하는 리포트, 서드파티 통합, 그리고 "어제까진 잘 되던" 내부 관리자 스크립트가 있습니다.

오래된 모바일 앱과 캐시된 클라이언트는 빈번한 문제입니다. 이들을 즉시 업데이트할 수 없기 때문입니다. 어떤 사용자는 앱 버전을 수주간 유지하기도 하고, 어떤 사용자는 간헐적 연결로 인해 이전 요청을 나중에 재시도하기도 합니다. 웹 클라이언트도 서비스 워커나 CDN, 프록시 캐시가 오래된 코드를 유지하면 "구버전"처럼 행동할 수 있습니다.

진짜 목표는 "하나의 큰 마이그레이션을 빨리 끝내기"가 아닙니다. 서로 다른 클라이언트가 다른 버전을 사용하는 상황에서도 각 단계가 독립적으로 작동하는 작은 단계들의 연속입니다.

실용적인 정의: 새로운 코드와 새로운 스키마를 어떤 순서로든 배포해도 시스템이 계속 동작해야 합니다.

이 사고방식은 전형적인 함정을 피하게 합니다. 예를 들어 컬럼이 생기기 전에 새 앱을 배포하거나 오래된 코드가 처리하지 못하는 새 컬럼을 추가하는 실수 등입니다. 변경을 먼저 추가적(additive)으로 계획하고, 단계를 나눠 롤아웃하며, 아무 것도 사용하지 않는다고 확신할 때만 옛 경로를 제거하세요.

기존 코드를 깨지 않는 추가적 변경으로 시작하기

무중단 스키마 변경으로 가는 가장 안전한 방법은 교체(replace)가 아니라 추가(add)입니다. 새 컬럼이나 새 테이블을 추가하는 것은 기존 코드가 이전 형태를 계속 읽고 쓸 수 있으므로 거의 문제가 생기지 않습니다.

이름 변경(renames)과 삭제(deletions)는 위험합니다. 이름 변경은 사실상 "새로 추가 + 옛것 제거"입니다. 이 중 옛것을 제거하는 단계가 오래된 클라이언트를 충돌시키는 지점입니다. 이름을 바꿔야 한다면 두 단계로 처리하세요: 먼저 새 필드를 추가하고, 옛 필드는 잠시 유지한 뒤 아무도 의존하지 않는 것이 확인되면 제거합니다.

컬럼을 추가할 때는 nullable로 시작하세요. nullable 컬럼은 옛 코드가 새 컬럼을 모른 채로 행을 삽입할 수 있게 해줍니다. 궁극적으로 NOT NULL을 원한다면 먼저 nullable로 추가하고 백필을 한 뒤 나중에 NOT NULL을 적용하세요. 기본값(defaults)이 도움이 될 수 있지만 주의해야 합니다. 일부 데이터베이스에서는 기본값을 추가하는 작업이 많은 행을 건드려서 변경이 느려질 수 있습니다.

인덱스는 "안전하지만 비용이 있는" 추가 항목입니다. 읽기를 빠르게 하지만 인덱스 생성과 유지가 쓰기를 느리게 할 수 있습니다. 어떤 쿼리가 인덱스를 사용할지 확실할 때 추가하고, 데이터베이스가 바쁠 때는 한가한 시간에 롤아웃을 고려하세요.

추가적 데이터베이스 마이그레이션을 위한 간단한 규칙:

• 새 테이블이나 컬럼을 먼저 추가하고, 기존 것은 그대로 둡니다.
• 새 필드는 데이터가 채워질 때까지 선택적(nullable)으로 만듭니다.
• 클라이언트가 업데이트될 때까지 기존 쿼리와 페이로드가 작동하도록 유지합니다.
• 제약조건(NOT NULL, unique, foreign keys)은 백필 후에 적용합니다.

오래된 클라이언트를 유지하면서 단계별로 롤아웃하기

무중단 스키마 변경을 단일 배포가 아니라 롤아웃으로 취급하세요. 목표는 오래된 버전과 새 버전의 앱이 사이드바이사이드로 실행되는 동안 데이터베이스가 점진적으로 새 형태로 이동하는 것입니다.

실용적 순서:

1. 호환되는 방식으로 새 스키마를 추가하세요. 새 컬럼이나 테이블을 만들고 널을 허용하며, 오래된 코드가 채우지 못하는 엄격한 제약을 피하세요. 인덱스가 필요하면 쓰기를 차단하지 않는 방식으로 추가하세요.
2. 두 가지 ‘언어’ 모두를 이해하는 백엔드 코드를 배포하세요. API가 옛 요청과 새 요청을 모두 수용하도록 업데이트하세요. 새 필드를 쓰되 옛 필드도 올바르게 유지하는 ‘듀얼 라이트(dual write)’ 단계가 혼합된 클라이언트 버전에서 안전합니다.
3. 기존 데이터를 소규모 배치로 백필하세요. 오래된 행들에 대해 새 컬럼을 점진적으로 채우세요. 배치 크기를 제한하고 필요하면 지연을 두며 진행 상황을 추적해 부하가 증가하면 일시중지할 수 있게 하세요.
4. 커버리지가 충분할 때만 읽기를 전환하세요. 대부분의 행이 백필되고 확신이 서면 백엔드를 기본적으로 새 필드를 읽도록 바꾸세요. 당분간은 옛 필드로 되돌아가는 폴백을 유지하세요.
5. 옛 필드는 마지막에 제거하세요. 오래된 모바일 빌드가 대부분 사라지고, 로그에 옛 필드 읽기가 없음을 확인하고, 롤백 계획이 준비되었을 때 옛 컬럼과 관련 코드를 제거하세요.

예: full_name을 도입했지만 오래된 클라이언트는 first_name과 last_name을 보낸다고 가정합니다. 일정 기간 동안 백엔드는 쓰기 시 full_name을 구성하고, 기존 사용자들을 백필한 뒤 기본적으로 full_name을 읽으면서 옛 페이로드를 계속 지원합니다. 채택이 명확해지면 옛 필드를 삭제합니다.

놀라움 없는 백필: 새 데이터를 안전하게 채우기

백필은 기존 행에 새 컬럼이나 테이블을 채우는 작업입니다. 대량의 데이터베이스 부하, 긴 잠금, "반쯤 마이그레이션된" 혼란스러운 동작을 초래할 수 있어 종종 무중단 변경 중 가장 위험한 부분입니다.

먼저 백필을 어떻게 실행할지 결정하세요. 소규모 데이터셋은 수동 런북으로 충분할 수 있습니다. 대규모 데이터셋은 반복 실행하고 안전하게 중단할 수 있는 백그라운드 워커나 스케줄 잡을 선호하세요.

작업을 배치로 나눠 데이터베이스에 가해지는 압력을 제어하세요. 수백만 행을 한 트랜잭션으로 업데이트하지 마세요. 예측 가능한 청크 크기와 배치 사이의 짧은 일시중단을 목표로 해 일반 사용자 트래픽이 원활하게 유지되도록 하세요.

실용 패턴:

• 인덱스된 키를 사용해 다음 1,000행 같은 소규모 배치를 선택합니다.
• 누락된 것만 업데이트합니다(이미 백필된 행을 다시 쓰지 마세요).
• 빠르게 커밋하고 잠깐 쉬세요.
• 진행 상황(마지막 처리된 ID나 타임스탬프)을 기록합니다.
• 실패 시 처음부터 다시 시작하지 않고 재시도합니다.

잡을 재시작 가능하게 만드세요. 전용 테이블에 간단한 진행 마커를 저장하고, 잡을 재실행해도 데이터가 손상되지 않도록 설계하세요. 예: new_field IS NULL 조건으로 업데이트하는 식의 멱등성(idempotent) 업데이트가 도움이 됩니다.

진행 중에 검증하세요. 새 값이 없는 행 수를 추적하고 몇 가지 기본 검사를 추가하세요. 예: 잔액이 음수인지, 타임스탬프가 기대 범위인지, 상태가 허용된 집합에 속하는지 등. 실제 레코드를 샘플링해 점검하세요.

백필이 완료되지 않은 동안 앱이 어떻게 행동해야 할지 결정하세요. 안전한 옵션은 폴백 읽기입니다: 새 필드가 null이면 옛 값을 계산하거나 읽습니다. 예: preferred_language를 추가하면 백필이 완료될 때까지 API는 preferred_language가 비어 있으면 프로필 설정에서 기존 언어를 반환하고, 완료 후에만 새 필드를 요구합니다.

혼합 클라이언트 버전에서의 API 호환성 규칙

스키마 변경을 배포할 때 모든 클라이언트를 통제할 수 있는 경우는 드뭅니다. 웹 사용자는 빨리 업데이트하지만 오래된 모바일 빌드는 수주간 활성 상태일 수 있습니다. 그래서 스키마 마이그레이션이 "안전"하더라도 하위 호환 API가 중요합니다.

새 데이터를 처음에는 선택사항으로 취급하세요. 요청과 응답에 새 필드를 추가하되 첫날부터 필수를 요구하지 마세요. 오래된 클라이언트가 새 필드를 보내지 않아도 서버는 요청을 받아들여 이전과 동일하게 동작해야 합니다.

기존 필드의 의미를 바꾸지 마세요. 필드 이름을 바꾸더라도 옛 이름을 계속 동작하도록 유지하면 괜찮습니다. 필드를 재사용해 새로운 의미를 부여하는 것이 미묘한 문제를 만드는 지점입니다.

서버 측 기본값은 안전망입니다. preferred_language 같은 새 컬럼을 도입할 때 값이 없으면 서버에서 기본값을 설정하세요. API 응답에 새 필드를 포함할 수 있고, 오래된 클라이언트는 이를 무시하면 됩니다.

대부분의 장애를 예방하는 호환성 규칙:

• 새 필드를 먼저 선택적으로 추가하고, 채택 후에만 강제하세요.
• 더 나은 동작을 뒤에 숨겨두더라도 옛 동작을 안정적으로 유지하세요.
• 새 필드가 없을 때 서버에서 기본값을 적용하세요.
• 혼합 트래픽을 가정하고 두 경로를 모두 테스트하세요: "새 클라이언트가 보냄"과 "옛 클라이언트가 생략함".
• 에러 메시지와 에러 코드를 안정적으로 유지해 모니터링이 갑자기 시끄러워지지 않게 하세요.

예: 가입 흐름에 company_size를 추가하면 백엔드는 해당 필드가 없을 때 "unknown" 같은 기본값을 설정할 수 있습니다. 최신 클라이언트는 실제 값을 보내고, 오래된 클라이언트는 계속 작동하며 대시보드는 읽을 수 있게 유지됩니다.

앱을 재생성(regenerate)할 때: 스키마와 로직을 동기화하는 방법

플랫폼이 애플리케이션을 재생성하면 코드와 설정을 깔끔하게 재빌드할 수 있습니다. 이는 무중단 스키마 변경에 도움이 됩니다. 작은 추가적 단계를 만들어 자주 재배포하면 수개월 동안 패치를 들고 다니는 부담을 줄일 수 있습니다.

핵심은 단일 소스 오브 트루스입니다. 데이터베이스 스키마가 한 곳에서 변경되고 비즈니스 로직이 다른 곳에서 변경되면 빠르게 일관성 떨어짐이 생깁니다. 변경을 어디에서 정의할지 결정하고 다른 것은 생성된 출력물로 취급하세요.

명확한 명명 규칙은 단계적 롤아웃에서 사고를 줄입니다. 새 필드를 도입하면 어느 것이 오래된 클라이언트용이고 어느 것이 새 경로인지 분명하게 만드세요. 예를 들어 새 컬럼을 status_v2로 이름 짓는 것은 status_new보다 여섯 달 뒤에도 의미를 유지하는 데 안전합니다.

재생성 후 무엇을 다시 테스트할지

변경이 추가적이라도 재빌드는 숨겨진 결합을 드러낼 수 있습니다. 재생성 및 배포 후에는 작은 핵심 흐름을 다시 확인하세요:

• 가입, 로그인, 비밀번호 재설정, 토큰 갱신.
• 핵심 생성 및 업데이트 동작(가장 많이 사용되는 것들).
• 관리자 및 권한 검사.
• 결제 및 웹훅(예: Stripe 이벤트).
• 알림 및 메시지(이메일/SMS, Telegram).

에디터를 열기 전에 마이그레이션 단계를 계획하세요: 새 필드를 추가하고, 양쪽 필드를 지원하는 상태로 배포하고, 백필하고, 읽기를 전환한 다음, 나중에 옛 경로를 제거하세요. 이 순서는 스키마, 로직, 생성된 코드가 함께 움직이게 하여 변경을 작고 검토 가능하며 되돌릴 수 있게 합니다.

장애를 유발하는 흔한 실수(및 피하는 방법)

무중단 스키마 변경 중 발생하는 대부분의 장애는 "무거운" 데이터베이스 작업에서 생기지 않습니다. 데이터베이스, API, 클라이언트 간 계약(contract)을 잘못된 순서로 변경해서 발생합니다.

일반적인 함정과 더 안전한 조치:

• 오래된 코드가 아직 읽을 때 컬럼 이름을 바꿈. 옛 컬럼을 유지하고 새 컬럼을 추가한 뒤 두 가지를 일정 기간 매핑하세요(둘 다 쓰거나 뷰를 사용하는 등). 아무도 옛 이름에 의존하지 않는 것을 증명한 뒤에만 이름을 바꾸세요.
• nullable 필드를 너무 일찍 필수로 만듦. 먼저 nullable로 추가하고, 코드가 모든 곳에서 쓰도록 배포한 뒤 오래된 행을 백필하고 마지막 마이그레이션에서 NOT NULL을 적용하세요.
• 테이블을 잠그는 대규모 단일 트랜잭션으로 백필함. 작은 배치로 백필하고 제한과 일시중단을 둬 진행 상황을 추적하세요.
• 쓰기보다 먼저 읽기를 전환함. 먼저 쓰기를 전환하고, 그다음 백필, 마지막으로 읽기를 전환하세요. 읽기를 먼저 바꾸면 빈 화면, 잘못된 합계, "필드 없음" 오류가 발생합니다.
• 오래된 필드를 증거 없이 삭제함. 오래된 필드는 생각보다 더 오래 유지하세요. 오래된 버전이 사실상 비활성 상태인지 지표로 확인하고, 폐기 창구를 공지한 뒤 제거하세요.

앱을 재생성하면 이름과 제약을 한 번에 "정리"하고 싶은 유혹이 듭니다. 그 유혹을 참으세요. 정리는 마지막 단계이지 첫 단계가 아닙니다.

좋은 규칙: 변경을 안전하게 앞으로 진행하고 되돌릴 수 없다면 생산 환경에 투입할 준비가 된 것이 아닙니다.

단계적 마이그레이션을 위한 모니터링과 롤백 계획

무중단 스키마 변경의 성공 여부는 두 가지에 달립니다: 무엇을 감시하느냐, 얼마나 빨리 중단할 수 있느냐.

배포가 끝났다는 것만 보는 대신 실제 사용자 영향에 해당하는 신호를 추적하세요:

• 업데이트한 엔드포인트의 API 에러율(특히 4xx/5xx 스파이크).
• 느린 쿼리(p95 또는 p99 쿼리 시간) — 수정한 테이블 대상.
• 쓰기 지연(피크 트래픽 중 삽입 및 업데이트에 걸리는 시간).
• 큐 깊이(백필이나 이벤트 처리용 작업이 쌓이는지).
• 데이터베이스 CPU/IO 사용량(변경 후 급격한 상승 여부).

듀얼라이트를 하는 경우(옛/새 컬럼 둘 다 쓰는 경우) 두 값을 비교하는 임시 로깅을 추가하세요. 단, 로그는 차이가 날 때만 기록하고, 레코드 ID와 짧은 이유 코드를 포함하며, 볼륨이 높으면 샘플링하세요. 마이그레이션 후 이 로깅을 제거하라는 리마인더를 만들어 영구적인 노이즈가 되지 않게 하세요.

롤백은 현실적으로 계획하세요. 대부분의 경우 스키마를 롤백하지 않습니다. 애플리케이션 코드를 롤백하고 추가적 스키마는 유지하는 방식이 더 흔합니다.

실용적인 롤백 런북:

• 애플리케이션 로직을 마지막 정상 버전으로 되돌립니다.
• 새 읽기를 먼저 비활성화한 다음 새 쓰기를 비활성화합니다.
• 새 테이블이나 컬럼은 유지하되 사용을 중지합니다.
• 백필을 중단하고 지표가 안정될 때까지 기다립니다.

백필에는 몇 초 안에 끌 수 있는 정지 스위치(피처 플래그, 설정 값, 잡 일시중지)를 만드세요. 또한 듀얼라이트 시작 시기, 백필 실행 시기, 읽기 전환 시기, "중단"의 의미를 사전에 소통해두어 긴급 상황에서 임기응변을 하지 않게 하세요.

빠른 배포 전 체크리스트

스키마 변경을 배포하기 직전에 잠시 멈춰 이 체크를 실행하세요. 혼합 클라이언트 버전에서 작은 가정을 놓치면 큰 장애로 이어집니다.

• 변경이 추가적(additive)인가? 마이그레이션이 테이블, 컬럼, 인덱스만 추가하고 기존 것을 제거하거나 이름을 바꾸거나 엄격하게 만들어 오래된 쓰기를 거부하지 않는지 확인합니다.
• 읽기가 두 형태 모두 작동하는가? 새 서버 코드는 "새 필드 존재"와 "새 필드 부재" 모두에서 오류 없이 작동합니다. 선택적 값은 안전한 기본값을 가집니다.
• 쓰기 호환성은 유지되는가? 새 클라이언트는 새 데이터를 보낼 수 있고 오래된 클라이언트는 옛 페이로드로도 성공해야 합니다. 서버가 두 포맷을 모두 수용하고 오래된 클라이언트가 파싱할 수 있는 응답을 생성하는지 확인합니다.
• 백필은 멈췄다 재시작해도 안전한가? 잡은 배치로 실행되고, 재시작해도 데이터 중복이나 손상이 없어야 하며 남은 행 수를 측정할 수 있어야 합니다.
• 삭제 날짜를 알고 있는가? 언제 레거시 필드나 로직을 제거할지에 대한 구체적 규칙이 있는가(예: X일 후 및 Y%의 요청이 업데이트된 클라이언트에서 오는지 확인).

재생성 플랫폼을 사용한다면 추가 점검: 마이그레이션하려는 정확한 모델에서 빌드를 생성하고 배포한 뒤, 생성된 API와 비즈니스 로직이 옛 레코드를 여전히 허용하는지 확인하세요. 흔한 실패는 새 스키마가 새 필수 로직을 의미한다고 가정하는 실수입니다.

또한 배포 후 문제가 생기면 무엇을 모니터링하고 어떤 것을 먼저 롤백할지(피처 플래그 끄기, 백필 일시중지, 서버 릴리스 되돌리기) 두 가지 빠른 행동을 적어두세요. 이것이 "빠르게 반응하겠다"는 추상적 다짐을 실제 계획으로 바꿉니다.

예시: 오래된 모바일 앱이 여전히 활성화된 상태에서 새 필드 추가하기

주문 앱을 운영한다고 합시다. delivery_window라는 새 필드가 필요하고 비즈니스 규칙상 필수화할 예정입니다. 문제는 오래된 iOS/Android 빌드가 여전히 사용 중이고, 며칠 또는 몇 주간 이 필드를 보내지 않을 수 있다는 점입니다. 데이터베이스에서 즉시 필수로 만들면 이들 클라이언트는 실패합니다.

안전한 경로:

• 1단계: 컬럼을 nullable로 추가하고 제약을 두지 않습니다. 기존 읽기/쓰기는 변경하지 않습니다.
• 2단계: 듀얼 라이트. 새 클라이언트(또는 백엔드)가 새 필드를 씁니다. 옛 클라이언트는 컬럼이 null을 허용하므로 계속 작동합니다.
• 3단계: 백필. 배송 방식에서 유추하거나 기본값을 "anytime"으로 설정해 옛 행을 채웁니다.
• 4단계: 읽기 전환. API와 UI가 먼저 delivery_window를 읽되 값이 없으면 유추된 값을 폴백으로 사용합니다.
• 5단계: 나중에 강제화. 채택과 백필이 완료되면 NOT NULL을 추가하고 폴백을 제거합니다.

각 단계 동안 사용자가 느끼는 변화는 지루함(boring)입니다(목표가 바로 그것입니다):

• 오래된 모바일 사용자는 데이터가 없다고 API가 거부하지 않으므로 계속 주문할 수 있습니다.
• 새 모바일 사용자는 새 필드를 보고 선택이 일관되게 저장됩니다.
• 운영과 지원팀은 필드가 점진적으로 채워지는 것을 보고 갑작스러운 누락은 보지 않습니다.

각 단계의 간단한 모니터링 기준: 새 주문에서 delivery_window가 비어있지 않은 비율을 추적하세요. 이 비율이 안정적으로 높고 "필드 누락" 검증 오류가 거의 0이면 백필에서 제약 강제화로 넘어가기 안전한 신호입니다.

다음 단계: 재현 가능한 마이그레이션 플레이북 만들기

한 번의 신중한 롤아웃은 전략이 아닙니다. 스키마 변경을 일상화하세요: 동일한 단계, 동일한 명명 규칙, 동일한 승인 절차. 그러면 다음 추가적 변경도 앱이 바쁘고 클라이언트가 다른 버전일 때도 지루하게(문제없이) 진행됩니다.

플레이북은 간결해야 합니다. 무엇을 추가하고, 어떻게 안전하게 배포하며, 언제 오래된 부분을 제거할지 답해야 합니다.

간단한 템플릿:

• 추가만 한다(새 컬럼/테이블/인덱스, 선택적 새 API 필드).
• 옛 구조와 새 구조를 모두 읽을 수 있는 코드를 배포한다.
• 소규모 배치로 백필하고 완료 신호를 명확히 한다.
• 동작 전환은 피처 플래그나 설정으로 하고 재배포에 의존하지 않는다.
• 컷오프 날짜와 검증 후에만 오래된 필드/엔드포인트를 제거한다.

낮은 위험의 테이블(새 선택적 상태, 메모 필드)로 시작해 전체 플레이북을 처음부터 끝까지 실행하세요: 추가적 변경, 백필, 혼합 버전 클라이언트, 정리 단계. 이 연습은 주요 재설계 시도 전에 모니터링, 배치 처리, 커뮤니케이션의 빈틈을 드러냅니다.

장기적 혼란을 막는 한 가지 습관: "나중에 제거"할 항목을 실제 작업으로 취급하세요. 임시 컬럼, 호환성 코드, 듀얼라이트 로직을 추가하면 즉시 정리 티켓을 만들고 담당자와 날짜를 지정하세요. 릴리스 문서에 작지만 지속적인 "호환성 부채" 메모를 남겨 가시성을 유지하세요.

AppMaster로 구축하면 재생성을 안전 절차의 일부로 취급할 수 있습니다: 추가적 스키마를 모델링하고, 전환 중에 옛/새 필드를 모두 처리하도록 비즈니스 로직을 업데이트한 뒤 재생성하여 소스 코드가 요구사항 변화에 따라 깔끔하게 유지되게 합니다. 이 워크플로우가 코드가 실제로 생성되는 노코드 환경에 어떻게 맞는지 보고 싶다면 AppMaster (appmaster.io)는 반복적이고 단계적인 배포 방식에 맞춰 설계되어 있습니다.

목표는 완벽함이 아니라 반복성입니다: 모든 마이그레이션에 계획, 측정, 그리고 철수 경로가 있어야 합니다.