마이그레이션은 한 줄이 아니라 되돌아오는 길이다

처음엔 스크립트 하나면 된다고 생각했습니다.

읽고, 바꾸고, 저장한다.

데이터가 많지 않을 때는 그게 제일 빠르게 보입니다.
실제로 빠릅니다.
한 번 실행하면 끝나는 작업처럼 보입니다.
그런데 마이그레이션은 실행하는 순간부터 질문이 달라졌습니다.

실패하면 어디까지 됐는지 알 수 있나요.

다시 돌려도 안전한가요.

되돌릴 수 있나요.

그 질문에 답이 없으면 스크립트가 아니라 도박에 가까웠습니다.

dry-run은 말로 하면 안 믿었습니다

“dry-run만 했습니다.”

이 말도 처음엔 믿었습니다.
근데 멀티에이전트나 긴 자동화에서는 말만으로 부족했습니다.
dry-run 전후로 레코드 수가 같은지, 대상 범위가 맞는지, 실제 write가 없었는지 봐야 했습니다.

제가 지금 좋아하는 형태는 이런 겁니다.

target_count_before: 22000
would_update: 21743
would_skip: 257
write_count_after: 0

숫자는 예시입니다.
중요한 건 전후 상태가 있다는 점입니다.
dry-run이 “안 썼다”는 주장을 하려면 쓰지 않았다는 증거가 있어야 합니다.

백필은 운영 기록이 필요했습니다

일회성 스크립트의 제일 큰 문제는 실행 후 기억이 사라지는 겁니다.

언제 돌렸는지, 어떤 버전으로 돌렸는지, 몇 건을 바꿨는지, 어떤 건 스킵했는지, 실패 후 재시도했는지.
그 기록이 없으면 다음 사람이 다시 추측합니다.
그 다음 사람이 저일 수도 있고요.

그래서 백필은 가능하면 마이그레이션 프레임워크 안으로 넣습니다.

거창한 시스템이 아니어도 됩니다.

idempotency key
run ledger
before/after count
rollback note
skip reason

이 다섯 가지가 있으면 훨씬 덜 무섭습니다.

특히 idempotency가 중요했습니다.
중간에 네트워크가 끊기거나, 프로세스가 죽거나, 같은 작업을 한 번 더 실행해야 할 때 중복 변경이 생기면 안 됩니다.

되돌릴 수 없는 일은 작을 때 해야 했습니다

또 하나 배운 건 타이밍입니다.

마이그레이션은 데이터가 적을 때 해야 합니다.
너무 당연한 말인데, 실제로는 자꾸 미룹니다.
지금은 기능이 급하고, 나중에 정리하자고 생각합니다.

근데 나중에는 데이터가 늘고, 사용자가 늘고, 예외가 늘고, 롤백 비용이 늘어납니다.
같은 한 줄 변경도 100건일 때와 100만 건일 때의 무게가 다릅니다.

초기 제품에는 황금 창이 있습니다.
아직 되돌릴 수 있고, 아직 사람이 전부 볼 수 있고, 아직 문제가 생겨도 밤새 고칠 수 있는 시기입니다.

그 창이 닫히면 같은 작업이 프로젝트가 됩니다.

제가 지금 쓰는 마이그레이션 체크

실행 전에는 이것만 봅니다.

질문	이유
대상 집합을 정확히 다시 만들 수 있나	재시도 때문
dry-run 전후 count가 있나	쓰기 없음 증명
실패 지점부터 재개 가능한가	중간 실패 때문
롤백 또는 보정 경로가 있나	되돌림 때문
실행 기록이 남나	다음 사람 때문

이 다섯 개가 없으면 아직 스크립트입니다.
마이그레이션이라고 부르기엔 약합니다.

요즘도 작은 데이터 수정은 유혹적입니다.
그냥 한 번 돌리면 끝날 것 같습니다.

그래도 먼저 되돌아오는 길을 봅니다.

가는 길보다 돌아오는 길이 더 비싸니까요.