04. Schema Change와 Pipeline 영향 상세

이 문서를 통해 아래 질문들에 답할 수 있게 됩니다.

• 운영 DB schema 변경은 pipeline의 어느 단계까지 영향을 줄 수 있는가?
• 컬럼 추가, rename, type 변경, null 정책 변경은 각각 어떤 위험을 만드는가?
• Java/Spring 백엔드 변경 PR에서 데이터 파이프라인 영향은 어떻게 점검하는가?
• schema change로 깨진 pipeline은 어느 범위부터 재처리해야 하는가?

개요

운영 DB schema 변경은 백엔드 내부 변경으로 끝나지 않을 수 있다.

컬럼 추가, rename, type 변경, enum 값 추가, null 허용 변경은 extract, parser, raw, warehouse, mart, dashboard까지 영향을 줄 수 있다.

특히 pipeline은 API보다 늦게 깨질 수 있다.

서비스 배포는 성공했지만 새벽 batch가 실패하거나, dashboard가 다음 날 틀릴 수 있다.

원리

pipeline은 source schema에 의존한다.

source schema가 바뀌면 다음 지점을 확인해야 한다.

• extract SQL 또는 CDC connector
• raw schema와 serialization format
• transform parser
• warehouse table
• mart SQL
• data quality rule
• dashboard와 downstream consumer

schema change review는 migration SQL만 보는 일이 아니다.

변경 유형별 영향

변경	위험	예시
nullable column 추가	낮음~중간	parser가 unknown field를 허용하면 안전
required column 추가	높음	과거 raw에는 값이 없음
column rename	높음	pipeline에는 삭제와 추가로 보임
type 변경	높음	numeric → varchar, bigint → uuid
enum 값 추가	중간~높음	transform switch 문 실패
의미 변경	매우 높음	paid_amount 기준 변경

이름은 같고 의미만 바뀌는 변경이 가장 위험하다.

검증 SQL이 통과해도 지표 의미가 달라질 수 있기 때문이다.

영향 전파 예시

orders.paid_amount -> orders.payment_amount rename
  -> extract SQL 실패
  -> raw_orders schema 변경
  -> transform code field mapping 실패
  -> fact_order_payment.paid_amount null
  -> mart_sales_daily 금액 누락
  -> dashboard 매출 급락

이 경로를 PR에서 미리 볼 수 있어야 한다.

운영 DB migration만 성공하면 끝나는 변경이 아니다.

백엔드 PR 체크

schema change:
  table: orders
  change: add column payment_method nullable
  source consumers:
    - order CDC connector
    - order_daily_mart pipeline
    - fraud feature extract
  required action:
    - raw schema accepts new field
    - mart does not use field yet
    - event schema unaffected
  backfill:
    - not required

이런 체크가 있어야 데이터 팀이 영향도를 판단할 수 있다.

백엔드 팀은 어떤 table과 column이 어떤 business meaning을 가지는지 설명해야 한다.

안전한 추가

nullable column 추가는 비교적 안전할 수 있다.

하지만 pipeline parser가 strict schema를 쓰면 unknown field로 실패할 수 있다.

반대로 parser는 통과하지만 mart가 새 field를 기대하면 과거 raw에 값이 없어 문제가 생긴다.

따라서 “추가니까 안전하다”가 아니라 consumer와 과거 데이터까지 확인한다.

Rename과 의미 변경

rename은 pipeline 관점에서 삭제와 추가다.

safe rollout은 보통 expand and contract 방식이다.

1. 새 column 추가
2. 백엔드가 old/new를 함께 write
3. pipeline이 new column을 읽도록 변경
4. 과거 데이터 backfill
5. quality 검증
6. old column 제거

의미 변경은 더 조심해야 한다.

같은 column 이름으로 gross amount에서 net amount로 바꾸면 과거와 현재 지표가 섞인다.

판단 축

• 변경된 column을 읽는 pipeline 목록을 찾는다.
• raw와 warehouse schema가 새 값을 받을 수 있는지 확인한다.
• 과거 raw나 fact를 새 schema로 다시 해석할 수 있는지 본다.
• 의미 변경은 새 column, 새 event, 새 metric으로 분리한다.
• migration 배포와 pipeline 배포 순서를 정한다.

실패 모델

• 운영 DB rename 후 새벽 extract SQL이 실패한다.
• enum 값 추가 후 transform switch default가 없어 task가 죽는다.
• nullable field가 mart에서 required처럼 쓰여 null 지표가 생긴다.
• 의미 변경을 문서화하지 않아 같은 metric 이름의 수치가 달라진다.
• schema 변경 후 과거 raw를 replay할 parser가 없다.

운영 지표

• schema_mismatch_count: source와 parser schema 불일치 수다.
• unknown_field_count: parser가 모르는 field 수다.
• null_rate_by_field: 새 column의 null 비율이다.
• transform_parse_failure_count: type이나 enum 변경으로 인한 실패 수다.
• downstream_breaking_change_count: 변경으로 깨진 mart나 dashboard 수다.

검증 SQL

SELECT COUNT(*) AS null_payment_method_count
FROM raw_orders
WHERE ds = DATE '2026-06-30'
  AND payment_method IS NULL;

SELECT payment_status, COUNT(*)
FROM raw_orders
WHERE ds = DATE '2026-06-30'
GROUP BY payment_status;

새 field나 enum 값은 분포를 확인해야 한다.

분포 검증 없이 mart rule을 바꾸면 조용히 잘못된 지표가 만들어진다.

개인 프로젝트 기준

개인 프로젝트에서는 schema change checklist를 README에 두는 것부터 시작한다.

운영 table column을 바꿀 때 summary table, raw table, batch SQL을 함께 검색한다.

작은 프로젝트라도 rename은 expand and contract 방식으로 연습하면 좋다.

기업 운영 기준

기업에서는 data contract와 schema registry, lineage 도구가 필요할 수 있다.

그러나 도구보다 중요한 것은 owner 간 사전 합의다.

백엔드 PR에는 데이터 파이프라인 영향 체크가 포함되어야 하고, pipeline owner가 승인할 수 있어야 한다.

실전 팁

• schema 변경 PR에서는 table 이름으로 pipeline 코드를 검색한다.
• enum 값 추가는 transform default와 quality rule을 함께 확인한다.
• column 의미 변경은 rename보다 위험하다고 본다.
• raw replay가 필요한 변경이면 legacy parser를 보관한다.
• 변경 후 첫 pipeline run은 row count와 null rate를 더 촘촘히 본다.

위험 신호!

• “DB migration은 통과했다”는 이유로 pipeline 영향 확인을 생략한다.
• source column rename을 같은 날 old column 삭제까지 한다.
• mart SQL이 운영 DB column 의미에 직접 의존한다.
• schema change 알림이 데이터 팀에 전달되지 않는다.
• 과거 raw를 읽는 parser가 현재 schema만 지원한다.

확인 질문

확인 질문

• schema change가 pipeline에 영향을 주는 경로는 무엇인가?
  • extract, raw schema, transform parser, warehouse table, mart SQL, quality rule, dashboard로 전파될 수 있다.
• column rename을 안전하게 하려면 어떤 절차가 필요한가?
  • 새 column 추가, dual write, pipeline 전환, backfill, 검증, old column 제거 순서가 안전하다.
• 의미 변경이 단순 type 변경보다 위험한 이유는 무엇인가?
  • 구조는 깨지지 않아도 같은 metric 이름의 business meaning이 바뀌어 지표가 조용히 틀릴 수 있기 때문이다.

참고 문서

• Martin Fowler, Evolutionary Database Design
• dbt Documentation, Source Freshness
• Debezium Documentation
• Martin Kleppmann, Designing Data-Intensive Applications