사례6건

6건 중 1~5번째

1. IL-0570 안 쓰는 테이블을 지우는 마이그레이션 직후 MySQL 쿼리가 막혀 crowdworks.jp에 1분쯤 접속하기 어려웠다

   CrowdWorks2026

   증상

   drop_table 마이그레이션을 실행한 직후부터 데이터베이스 쿼리가 막히기 시작했고, crowdworks.jp에는 1분쯤 접속이 잘 되지 않았다. 마이그레이션은 끝내 타임아웃으로 실패했고 서비스는 저절로 복구됐다.

   잠금 경합과 교착간헐적 연결 실패

   촉발

   이미 쓰지 않는 테이블을 지우려고 drop_table 마이그레이션을 실행했다. 이 테이블에는 트래픽이 매우 많은 테이블을 가리키는 외래 키 제약이 걸려 있었다.

   원인

   배포 결함

   구성 요소

   데이터베이스스키마 마이그레이션

   기여 요인

   –

   후속 조치

   • 대상 마이그레이션은 execute 'SET SESSION lock_wait_timeout = 3' 으로 MDL 대기 상한을 줄여, 대기가 길어지기 전에 실패하게 한다. 3초는 운영하면서 조정할 임시 값이다.
   • execute는 change에서 되돌릴 수 없어 롤백 때 ActiveRecord::IrreversibleMigration 이 나므로, def change 대신 def up 과 def down 으로 쓴다. 롤백 쪽 DDL도 같은 MDL을 잡으므로 up과 down 모두 대상 DDL 앞에 설정을 둔다.
   • 중간에 실패해 일부만 적용되는 일을 피하려고 마이그레이션 하나에 대상 DDL은 하나만 둔다.
   • 실패할 때 다른 마이그레이션까지 휩쓸리지 않도록 대상 DDL을 담은 마이그레이션은 따로 릴리스한다.
   • 대상 마이그레이션은 트래픽이 적은 시간대에 실행한다.
   • 대상 조건과 대응 방법의 자세한 내용은 db/migrate/README.md 에 둔다.
   • AGENTS.md 의 참조 표에 db/migrate/ → db/migrate/README.md 한 줄을 더해 Copilot과 AI 에이전트가 리뷰할 때 이 규칙을 보게 한다.
   • db/migrate/** 를 바꾼 PR에 자동으로 달리는 기존 코멘트의 체크리스트에 이번 확인 항목을 더한다.

   사례 보기
2. IL-0369 데이터베이스 마이그레이션이 잠금에 막히는 동안 Railway 백엔드 복제본이 헬스 체크에 실패해 대시보드와 API 가 멈췄다

   Railway2025

   증상

   Railway 백엔드 API 가 트래픽을 받지 못해 대시보드 접속, CLI 작업, GitHub 기반 배포 처리, 로그인, API 가 멈췄다. 이미 돌고 있던 배포는 계속 온라인이었고, 이 시스템들을 쓰지 않은 사용자는 영향을 받지 않았다.

   프로브 실패잠금 경합과 교착데이터베이스 과부하서비스 중단

   촉발

   엔지니어들이 15:03 UTC 에 데이터 마이그레이션이 들어간 데이터베이스 스키마 변경을 머지했다. 이 마이그레이션은 약 10억 행이 있고 많이 쓰는 테이블에 nullable 열을 더하는 것이었다.

   원인

   배포 결함

   구성 요소

   데이터베이스데이터베이스 프록시와 커넥션 풀러스키마 마이그레이션라이브니스·레디니스 프로브

   기여 요인

   의존성에 묶인 헬스 체크

   후속 조치

   • 데이터베이스 연결 수를 늘리고, PgBouncer 가 그 한도 안에서 동작하도록 다시 설정한다.
   • 오래 도는 쿼리를 고쳐 행 잠금 문제가 다시 나지 않게 한다.

   사례 보기
3. IL-0554 데이터베이스 마이그레이션의 긴 쿼리가 Postgres 커넥션을 고갈시켜 Sentry US 의 사이트와 수집이 22분 동안 멈췄다

   Sentry2024

   증상

   2024년 10월 10일 오후 3시 42분부터 4시 4분 PT까지 Sentry US 의 사이트와 이벤트 수집을 모두 쓸 수 없었다. 상태 페이지는 Postgres 데이터베이스 문제로 사이트를 쓸 수 없다고 알렸다.

   서비스 중단데이터베이스 과부하

   촉발

   RunSQL 명령으로 실행한 데이터베이스 마이그레이션에 잠금 타임아웃과 구문 타임아웃이 걸려 있지 않아 쿼리가 오래 돌았다.

   원인

   배포 결함

   구성 요소

   데이터베이스스키마 마이그레이션

   기여 요인

   설정 테스트 부재런북 부재

   조치

   • 수정을 적용했고, 대시보드와 이벤트 수집이 회복하기 시작했다.

   후속 조치

   • 마이그레이션 프레임워크 안의 더 견고한 방법으로 바꿔 RunSQL 명령을 아예 없앤다.
   • 데이터베이스 프레임워크를 최신 버전으로 올린다. 새 버전은 전에 RunSQL 로 하던 작업 일부를 직접 처리한다.
   • 마이그레이션 중에 잠금이나 타임아웃 문제가 생겼을 때 복구를 안내하는 런북을 만들었다.
   • 더 빨리 대응하고 앞으로의 중단 시간을 줄이도록 알림과 관측 도구를 보강했다.

   사례 보기
4. IL-0523 TANF-app 의 운영 배포가 PostgreSQL 마이그레이션 실패로 두 달 동안 막힘

   U.S. Department of Health and Human Services2023

   증상

   2023년 9월 7일 TANF-app 의 sprint 80 운영 배포가 실패했고, 9월 20일 sprint 82 배포는 디스크 공간 오류로 실패했다. 그 뒤 11월 9일까지 운영에 배포하지 못했다.

   배포 실패노드 디스크 가득 참

   촉발

   2023년 9월 7일 sprint 80 배포에서 이미 배포된 마이그레이션 search_indexes 0016 을 지웠고, 9월 20일 sprint 82 배포가 이 마이그레이션을 다시 만들어 큰 마이그레이션 0017 과 함께 운영 데이터베이스에서 돌렸다.

   원인

   배포 결함

   구성 요소

   데이터베이스스키마 마이그레이션

   기여 요인

   장애 중첩자동 테스트 공백스테이징 불일치런북 부재

   감지

   운영 배포가 실패하면서 드러났다. 9월 7일 sprint 80 배포와 9월 20일 sprint 82 배포가 차례로 실패했고, 9월 20일 배포에서 디스크 공간 오류가 났다.

   조치

   • 11월 8일 운영 데이터베이스 인스턴스 크기를 키우고 마이그레이션을 다시 돌렸다. 이번에는 빈 문자열을 정수로 바꾸는 오류로 마이그레이션이 실패했다.
   • 운영 데이터베이스의 백업을 만들었다.
   • `search_indexes` 테이블을 모두 비웠다. 팀은 여기서 운영 데이터를 잃는 것을 걱정하지 않았다.
   • sprint 82 릴리스를 다시 배포해 운영을 sprint 82 로 되살렸고, 배포가 다시 가능해졌다.
   • 빈 문자열 버그를 고쳤다.

   후속 조치

   • 데이터베이스 문제 해결 절차를 기술 문서에 더한다.
   • 위키 페이지와 운영 플레이북에 흔한 문제와 대응을 정리한다.
   • Failed-Deployment-Troubleshooting 문서에 데이터베이스 문제 절을 만들고 cf revisions 명령을 적는다.
   • 운영에 직접 한 변경을 모은 GitHub 레포를 만들어, 비슷한 문제가 다시 날 때 길잡이로 쓴다.
   • 운영 디버깅 세션의 터미널 출력을 저장한다.
   • 코드 리뷰에서 지킬 Django 마이그레이션 모범 사례를 만든다.
   • develop 에 머지된 마이그레이션은 고치지 않고, 그 시점부터 모델을 바꾸는 새 마이그레이션을 쓴다.
   • 자동 생성된 마이그레이션 이름을 알아보기 쉬운 이름으로 바꾼다. 이름만 보고 내용을 알 수 없으면 조사하기 어렵다.
   • 자동 생성 마이그레이션은 모델 변경 하나에 하나만 두고, PR 하나에서 모델을 여러 번 바꾸면 마이그레이션을 다시 생성한다.
   • 시험에 쓸 데이터베이스 시딩과 백업을 어떻게 할지 논의 자리를 만든다.

   교훈

   계획에 없던 일이라 많은 개발자가 손을 보태야 했고, 팀이 작아 분야마다 모든 사람이 필요했다. 팀은 문제와 대응을 일찍 문서로 남겨 더 적은 사람으로 대응할 수 있게 하자고 했다. 작업 중인 코드를 raft, qasp, sandbox 환경에 배포한 뒤 마이그레이션을 바꾸면 그 환경에서 충돌이 난다. 대용량 데이터와 공백 채움이 없는 레코드 같은 예외 상황은 시험하지 않았고, 개인정보를 지운 운영 데이터베이스 사본이 있으면 실제 데이터로 더 많이 시험할 수 있다.

   사례 보기
5. IL-0524 인덱스를 다시 만드는 마이그레이션이 운영에서 Transactions 테이블을 잠가 Open Collective 서비스가 느려짐

   Open Collective2023

   증상

   2023년 4월 4일 09:13 UTC 에 배포를 시작하고 7분 뒤인 09:20 UTC 에 서비스 성능 저하가 보였다. 운영에서 실행한 마이그레이션이 Transactions 테이블 전체를 잠근 상태였다.

   잠금 경합과 교착데이터베이스 과부하

   촉발

   2023년 4월 4일 09:13 UTC 에 성능을 높이려고, 소프트 삭제된 행을 빼고 Transactions 테이블의 인덱스를 다시 만드는 마이그레이션을 배포했다.

   원인

   배포 결함

   구성 요소

   데이터베이스스키마 마이그레이션

   기여 요인

   리뷰 누락스테이징 불일치

   감지

   배포를 시작하고 7분 뒤인 09:20 UTC 에 서비스 성능 저하를 알아챘다.

   조치

   • 마이그레이션을 죽였지만 Transactions 테이블은 잠긴 채로 남았다.
   • 쿼리를 줄이려고 프런트엔드를 점검 모드로 돌렸다. 사용자에게는 분명한 안내 문구가 보였다.
   • 데이터베이스에 붙어 있던 다른 연결을 닫았다.
   • 새 인덱스 생성을 취소하고 10:00 UTC 부터 옛 인덱스를 되살렸으며, 10:05 UTC 에 복원이 끝나 성능이 정상으로 돌아왔다.
   • 10:08 UTC 에 프런트엔드를 되살리고 문제가 해결됐다고 공식으로 확인했다.

   후속 조치

   • vegeta 같은 도구로 로컬에서 운영 부하를 흉내 내는 스크립트를 더한다.
   • 이런 마이그레이션은 정해진 점검 시간대에 돌린다.
   • 앞으로 마이그레이션은 새 인덱스를 먼저 만들고 옛 인덱스를 나중에 지운다.
   • PR 을 머지하기 전에 다른 엔지니어의 리뷰를 꼭 받는다. 이번 PR 은 팀에 공유됐지만 리뷰되지 않았다.

   교훈

   옛 인덱스를 지우고 새 인덱스를 만드는 방식은 쿼리가 끊임없이 들어오는 테이블에서 너무 낙관적이었다. 로컬과 staging 에서 시험해도 부하가 걸린 환경에서 마이그레이션을 돌려 볼 도구가 없으면 이런 문제를 미리 잡지 못한다. 문제를 빨리 알아채고 엔지니어 두 명이 함께 조사한 것과, 사용자에게 분명한 안내를 보이면서 영향을 줄인 프런트엔드 점검 모드는 도움이 됐다.

   사례 보기

원인별1