MMX Beta Project Documents 계획, 근거, 댓글이 같은 기록으로 남는 작업 저장소

ALEMBIC_MIGRATION_DRIFT_20260523

  • 문서 작성자: 덱스PM
  • 문서 오너: 덱스PM
  • 작성일: 2026-05-23
  • 상태: Closed

이슈 개요

MMX api 서비스의 Alembic 마이그레이션 상태를 점검하던 중, Cloud Run 기동 실패를 유발한 multiple heads 문제는 해소했지만, alembic check 기준으로는 여전히 모델 메타데이터와 실제 DB 스키마 사이에 drift가 남아 있음이 확인되었다.

이 이슈는 단순히 head 충돌을 막는 수준이 아니라, 실제 운영 기준에서 Alembic upgrade 경로와 ORM 모델 정합성이 깨끗한 상태인지 끝까지 점검하고 수정한 뒤 클로징하는 것을 목표로 한다.

최초 관측 사실

  1. mmx-api 배포 시 컨테이너 entrypoint의 alembic upgrade head가 실패했다.
  2. 당시 Alembic head가 2개였다.
    • 9d04ce19b61e
    • b7c9d1e2f3a4
  3. merge migration c1d2e3f4a5b6_merge_project_document_release_head.py 추가 후, mmx-api-00076-npw 배포는 성공했다.
  4. 하지만 후속 점검에서 alembic check가 다수의 new upgrade operations를 검출했다.

현재 확인된 drift 범주

1. 과거 임시 테이블 / 잔재성 스키마

  • deep_temp_tbl가 DB에는 남아 있으나 현재 모델 메타데이터에는 없다.

2. 인덱스 / 제약조건 naming drift

  • project_document_comments
  • project_document_releases
  • studio_scenarios
  • users.username

기존 migration에서 직접 만든 인덱스명과 현재 ORM 자동 naming 기대값이 완전히 일치하지 않는다.

3. 모델 누락 또는 과거 migration 반영 불일치

  • scenarios.thumbnail_id
  • scenarios.shortcut_vid_id
  • scenarios.trailer_id

과거 migration에는 있으나 현재 모델 기준에서는 유지 여부가 불명확하다.

4. nullable / default 정합성 차이

  • users.google_sub
  • users.email
  • users.name
  • users.is_tester
  • users.tokens
  • users.last_login_at
  • game_status.genre_tags
  • game_status.created_at
  • game_status.updated_at
  • media.created_at

이슈 처리 목표

  1. Alembic head를 단일 상태로 유지한다.
  2. alembic current, alembic heads, alembic check 기준에서 운영 가능한 정합성을 확보한다.
  3. drift 항목을 유지 / 제거 / 모델 반영 / migration 보정으로 분류한다.
  4. 수정 과정과 판단 근거를 상세히 기록한다.
  5. 완료 후 운영 규칙을 별도 decision/report 문서로 정리한다.

처리 원칙

  1. 운영 DB에 이미 존재하는 구조는 실제 사용 여부를 확인하고 함부로 제거하지 않는다.
  2. autogenerate 결과를 그대로 적용하지 않고, 항목별 의미를 해석한 뒤 수동 검토한다.
  3. head 충돌 방지와 drift 청소를 분리해서 기록한다.
  4. 이슈가 완전히 닫히기 전에는 상태를 Closed로 바꾸지 않는다.

진행 로그

2026-05-23 06:xx 1차 확인

  • alembic heads 결과: 단일 head c1d2e3f4a5b6
  • alembic current 결과: 단일 head c1d2e3f4a5b6
  • alembic check 결과: drift 다수 검출
  • 임시 autogenerate 파일로 drift 목록을 캡처한 뒤 폐기했다.

2026-05-23 06:xx 2차 정리 시작

  • ORM 쪽 불필요한 index=True로 인한 naming drift 일부를 먼저 정리하기 시작했다.
  • 단, 이 단계만으로 drift 전체가 해소되지는 않음을 확인했다.

2026-05-23 06:xx 3차 정합화

  • DeepTemp 모델을 추가해 deep_temp_tbl을 메타데이터에 다시 편입했다.
  • Scenario 모델에 thumbnail_id, shortcut_vid_id, trailer_id를 반영했다.
  • users, game_status, media의 nullable/default 정합성을 맞추는 migration f4e5d6c7b8a9_align_alembic_schema_with_models.py를 추가했다.
  • legacy index/constraint naming에 맞추어 GameStatus, ProjectDocumentComment, ProjectDocumentRelease, StudioScenario, User 모델 정의를 보강했다.

2026-05-23 06:xx 최종 검증

  • alembic heads 결과: 단일 head f4e5d6c7b8a9
  • alembic current 결과: 단일 head f4e5d6c7b8a9
  • alembic check 결과: No new upgrade operations detected.
  • 순환 FK 경고(media ↔ scenarios)는 남아 있으나, drift 발생 없이 warning 수준임을 확인했다.
  • 상세 해결 과정은 ALEMBIC_MIGRATION_DRIFT_resolution_20260523에 기록했다.

종료 판단

  • multiple heads 문제 해결 완료
  • drift 분류 완료
  • 모델 및 migration 정합화 완료
  • alembic check clean 확보
  • 상세 보고서 작성 완료

따라서 본 이슈는 Closed 처리한다.

종료 조건

아래 조건을 모두 만족하면 이슈를 닫는다.

  1. drift 항목 분류 완료
  2. 필요한 모델/마이그레이션 수정 완료
  3. alembic heads 단일 head 유지 확인
  4. alembic current 정상 확인
  5. alembic check 결과를 기준으로 운영 허용 상태 확인
  6. 수정/판단 근거를 report에 상세 기록
  7. 배포 후 live 검증 완료

댓글