배포 순서와 DB 마이그레이션: 기능 하나를 배포까지 내보내며 알게 된 것들

기능 하나를 처음부터 끝까지 혼자 내보냈다. 이슈 만들기 → 브랜치 → 구현 → 테스트 → PR → 머지 → 배포 → 검증까지.

코드 쓰는 건 전체의 절반도 안 됐다. 나머지 절반에서 계속 걸렸고, 그게 전부 "몰라서" 걸린 거였다. 검색해도 잘 안 나오는 종류다 — 팀마다 다르고, 아는 사람은 설명할 필요를 못 느끼는 것들이라.

1. 배포에는 순서가 있다

프론트와 백엔드를 같이 고쳤으면 어느 쪽을 먼저 올리느냐가 문제가 된다. 동시에 안 올라간다. 사이에 몇 분이 뜨고, 그동안 서비스가 깨질 수 있다.

필드를 없애는 작업이라면 이렇게 갈린다.

순서	백엔드	프론트	그 사이
백엔드 먼저	필드 안 받음	아직 보냄	정상 — 여분 필드는 무시
프론트 먼저	필수라고 요구	안 보냄	전부 에러

규칙은 **"받아주는 쪽을 먼저 넓힌다"**다.

필드 추가: 백엔드가 먼저 받을 수 있게 → 그다음 프론트가 보내기 시작
필드 제거: 백엔드가 먼저 없어도 되게 → 그다음 프론트가 안 보내기 시작

둘 다 백엔드가 먼저다. 관대해지는 쪽이 먼저 나간다.

2. 앱을 배포해도 DB는 안 바뀐다

이게 제일 착각하기 쉬웠다. 코드에 SQL 파일을 커밋하고 배포하면 테이블이 바뀔 것 같은데 아니다. 마이그레이션은 사람이 따로 실행한다.

그래서 이런 사고가 난다 — 새 컬럼을 쓰는 코드가 배포됐는데 그 컬럼이 DB에 없다. 앱은 잘 뜨고, 그 기능을 쓰는 순간 터진다.

관리 방식은 팀마다 다른데, 보통 적용 여부를 파일에 기록해둔다.

-- Applied-Staging:    2026-08-18
-- Applied-Production: ____-__-__

3. 내 커밋만 나가는 게 아니다

배포는 보통 브랜치 상태를 내보내는 것이지 "내 커밋"을 내보내는 게 아니다. 개발 브랜치를 배포 브랜치로 병합하면 그동안 다른 사람들이 머지한 것도 전부 같이 나간다.

실제로 내 작업을 배포하면서 다른 사람 작업 여러 개가 함께 실려 나갔다.

그래서 배포 전에 본다.

git log 이전배포지점..dev --oneline

이 목록이 이번에 나가는 전부다. 모르는 커밋이 있으면 그 사람에게 확인한다. 특히 DB 마이그레이션이 포함됐는지 봐야 한다 — 내 작업엔 없어도 남의 작업엔 있을 수 있다.

4. 로컬에서 검증 안 되는 것들이 있다

"로컬에선 잘 되는데요"가 통하지 않는 영역이 있다.

안 되는 것	왜
외부 서비스 콜백	외부에서 내 노트북으로 못 들어온다
외부 API 연동	키가 배포 환경에만 있다
게이트웨이 경유 경로	로컬엔 그 라우팅이 없다
실제 데이터 기반 동작	로컬 DB는 초기 상태다

실력 문제가 아니라 구조상 안 되는 거다. 미리 알고 일정에 반영해야 한다. "구현 다 하고 마지막에 확인해야지" 하면 막판에 막힌다.

5. 문서와 코드는 어긋난다

기획서에 적힌 컬럼명이 실제 DB에 없는 경우가 있었다. 문서를 쓴 뒤에 스키마가 바뀌었거나, 처음부터 다르게 적힌 거다.

그래서 구현 전에 실물을 확인한다.

컬럼명 → 스키마 파일이나 DB
API 응답 필드 → 실제 응답이나 코드
목록 데이터 → 초기화 SQL이 아니라 실제 DB

마지막 건 따로 한 번 데였다. 초기 데이터 파일에 없다고 "이 값은 없다"고 결론 냈는데, 운영 DB에는 나중에 추가돼 있었다.

문서가 틀렸으면 고쳐서 알린다. 그냥 넘어가면 다음 사람이 또 걸린다.

6. 테스트가 못 잡는 것들이 있다

테스트를 다 통과했는데도 안 잡히는 종류가 있다.

항상 성공을 반환하는 API — 정보를 숨기려고 항상 200을 주는 엔드포인트는 내부 로직이 완전히 망가져도 계약상 정상이다. 테스트도 통과한다.

상태를 가려서 보여주는 화면 — 거절을 "확인 중"으로 보여주면 전 건 실패도 정상처럼 보인다.

부분 수정에서 값이 지워지는 것 — 폼에서 입력칸만 지우고 요청 객체를 안 고치면 그 필드가 빈 값으로 가서 기존 값을 덮어쓴다. 컴파일도 되고 테스트도 통과한다.

이런 건 코드를 눈으로 읽어서 찾는다. "이 값을 읽는 데가 어디지"를 먼저 찾는 습관.

7. 되돌리는 것도 배포다

시도했다가 아니라고 판명나면 되돌린다. 그 되돌리기도 똑같이 이슈 만들고 PR 올리고 배포한다. 조용히 지우지 않는다.

기록이 남아야 다음 사람이 "왜 이렇게 했다가 원복했지"를 알 수 있다.

8. 남의 손이 필요한 일은 먼저 요청한다

외부 서비스 키, 권한, 다른 팀의 확인 — 이런 건 내가 아무리 빨리 해도 상대 일정에 달려 있다. 구현 끝나고 요청하면 그만큼 통째로 밀린다.

작업 시작할 때 **"내가 못 하는 게 뭐지"**를 먼저 뽑아서 그것부터 요청해두는 게 낫다.

남길 것

관대해지는 쪽이 먼저 배포된다. 필드 추가든 제거든 백엔드가 먼저.
앱 배포가 DB를 바꾸지 않는다. 마이그레이션은 별도 작업이고, 적용 후 기록까지가 한 세트.
배포 단위는 "내 커밋"이 아니라 "브랜치 상태"다. 나가기 전에 커밋 목록을 확인한다.
로컬에서 검증 불가능한 영역이 있다. 일정에 미리 반영한다.
문서보다 실물을 믿는다.
테스트가 통과해도 안심할 수 없는 경로가 있다.
되돌리기도 정식 배포다.
남의 손이 필요한 건 제일 먼저 요청한다.

더 봐야 할 것

마이그레이션을 배포 파이프라인에 넣는 도구들은 어떻게 다른가
기능 플래그로 배포와 노출을 분리하면 순서 문제가 줄어드는지
배포 후 문제가 생겼을 때, 앞으로만 가는지(수정 배포) 뒤로도 가는지(롤백)