회원가입 정책 백필 SQL 누락 키 추가로 조용한 장애 예방

백필 SQL에 누락된 키 하나를 추가했다. 작은 수정이지만, 이게 빠져 있었으면 꽤 조용한 장애가 날 뻔했다.

배경 — 왜 백필 SQL이 필요했는가

회원가입 정책(SIGNUP_POLICY)을 DB에 구성값으로 관리하기 시작하면서, 기존에 코드 레벨 하드코딩으로 동작하던 항목들을 마이그레이션하는 작업이 진행됐다. 이번 마이그레이션 대상은 총 4개 키였음.

파일명이 phone_email_required로 끝나 있어서, 처음 SQL을 작성할 때 phoneRequired, emailRequired 두 가지에 집중하다 보니 nameCheckRequired가 INSERT 구문에서 빠졌다. 흔한 실수다. 특히 정책 키가 여러 개일 때 하나씩 추가하다 보면 마지막 항목이 누락되는 경우가 생긴다.

뭐가 문제였는가

nameCheckRequired 키가 DB에 없으면, 애플리케이션이 해당 키를 읽을 때 두 가지 중 하나로 동작한다.

// 키 없을 때의 전형적인 처리 패턴

// Case 1 — null/undefined로 떨어지고 기본값 처리
const nameCheckRequired = policy.nameCheckRequired ?? false;
// → 실명 확인이 조용히 '비필수'로 처리됨

// Case 2 — 키 없으면 예외 던짐
const nameCheckRequired = policy.getRequired('nameCheckRequired');
// → 가입 플로우에서 런타임 오류 발생

Case 1이 더 위험하다. Case 2는 에러가 터지니까 바로 발견되는데, Case 1은 실명 확인이 조용히 꺼진 상태로 서비스가 돌아간다. 정책 검증이 빠진 채 가입이 완료되는 것. 운영 중에 이런 케이스가 누적되면 나중에 데이터 정합성 맞추는 작업이 훨씬 커진다.

이번 케이스는 다행히 배포 전 SQL 리뷰 단계에서 잡혔다. 팀 내에서 백필 SQL은 반드시 "삽입하는 키 목록 == 스펙 문서의 키 목록"을 체크리스트로 확인하는 루틴이 있는데, 거기서 걸린 것.

수정 내용

sql/DML_20260514_signup_policy_phone_email_required.sql 파일에 nameCheckRequired 키를 INSERT 구문에 추가해서 4개 키가 모두 포함되도록 맞췄다.

-- 수정 전 (phone, email 2개만 삽입)
INSERT INTO signup_policy (policy_key, policy_value, created_at)
VALUES
  ('phoneRequired', 'true', NOW()),
  ('emailRequired', 'true', NOW());

-- 수정 후 (4키 완전)
INSERT INTO signup_policy (policy_key, policy_value, created_at)
VALUES
  ('phoneRequired',      'true', NOW()),
  ('emailRequired',      'true', NOW()),
  ('nameCheckRequired',  'true', NOW()),
  -- 4번째 키
  (...);

커밋 메시지에 "(4키 완전)"이라고 명시한 건 의도적이었다. 나중에 이 SQL 파일을 보는 사람이 "이 파일에서 몇 개 키 다뤘지?"를 바로 알 수 있게 하기 위해서. 백필 SQL은 한 번 실행되면 끝이라 히스토리가 곧 문서인 경우가 많다.

회고

백필 SQL 작성할 때 실수가 잦은 이유는 보통 두 가지다.

• 파일명이나 티켓 제목이 일부 항목만 가리킬 때 — "phone_email_required"라고 이름 붙여놓으면 자연스럽게 그 두 가지만 생각하게 된다. 이름이 작업 범위를 암묵적으로 제한해버리는 것.
• 항목이 많아질수록 마지막 항목 누락 — 특히 복붙해서 수정하는 방식으로 SQL 짤 때 마지막 행이 빠지기 쉽다.

팀에 공유한 게 하나 있다면, DML 파일 작성할 때 상단 주석에 "대상 키 목록"을 먼저 적어두고, 아래 INSERT 구문이 그 목록과 1:1로 매핑되는지 눈으로 체크하는 습관. 간단한데 의외로 잘 지켜지지 않는다. 이번 건을 계기로 PR 템플릿에 백필 SQL 체크리스트 항목 하나 더 추가했음.

작은 SQL 한 줄이지만, 정책 테이블 백필은 운영 환경에서 한 번 빠지면 재실행 타이밍 잡기가 까다롭다. 가볍게 보지 않는 게 맞다.

다음엔 DML 파일명도 전체 키 범위를 반영하도록 네이밍 가이드를 정리해볼 생각이다.

🛒 이 글과 어울리는 추천 상품

• 기계식키보드 쿠팡에서 보기 →
• 모니터암 쿠팡에서 보기 →
• 노이즈캔슬링헤드폰 쿠팡에서 보기 →

*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.