왜 Alembic은 기본적으로 데이터베이스용 Git인가 (그리고 왜 필요할까) 🗄️

Source: Dev.to

위의 링크에 있는 글 전체를 번역하고 싶으신가요? 번역이 필요한 정확한 텍스트(본문)를 제공해 주시면, 요청하신 대로 마크다운 형식과 코드 블록, URL은 그대로 유지하면서 한국어로 번역해 드리겠습니다.

Alembic: 데이터베이스 버전‑컨트롤

문제 상황

늦은 금요일 오후. 일주일 내내 작업해 온 기능에 Deploy 버튼을 눌러 배포하고, 앱이 라이브됩니다. 모든 것이 멋지게 보이지만—2분 정도 지나면 오류 로그가 불빛처럼 켜지기 시작합니다.

범인? 프로덕션 데이터베이스에 중요한 ALTER TABLE SQL 스크립트를 실행하는 것을 누군가 잊어버렸습니다.

개발자는 코드에 대해 꼼꼼합니다. Git으로 모든 문자 변화를 추적하고, 풀 리퀘스트를 검토하며, 브랜치를 관리합니다. 하지만 데이터베이스 스키마에 관해서는 상황이 종종 엉망이 됩니다. 우리는 다음과 같이 행동합니다:

• 기억에 의존
• Slack에 쿼리를 복사‑붙여넣기
• db_update_final_v3.sql 같은 이름이 형편없는 파일을 공유

Python 생태계(특히 SQLAlchemy)에서 작업한다면, 훨씬 나은 방법이 있습니다: Alembic.

Alembic이란?

Alembic = 데이터베이스용 버전 컨트롤

데이터베이스 관리 도구에 직접 로그인해 테이블을 수동으로 수정하는 대신, Alembic은 Python 스크립트로 스키마 변화를 정의하게 해줍니다.

간단한 예시

사용자 인증 시스템을 만든다고 가정해 봅시다.

몇 달 뒤, 제품 팀에서 last_login_date 컬럼을 추가하고 싶어합니다.

Alembic 없이

• SQL 명령을 직접 실행한다.
• 팀원들이 같은 명령을 로컬 환경에 적용했는지 기억해 주길 바란다.

Alembic 사용

1. 터미널에서 새로운 마이그레이션 스크립트를 생성한다:

   alembic revision -m "add last login date to users"

2. Alembic은 두 개의 필수 함수를 포함한 새 파일을 만든다:

   def upgrade():
       # 컬럼을 추가하는 코드
       pass
   
   def downgrade():
       # 컬럼을 제거하는 코드
       pass

3. 적절한 upgrade()와 downgrade() 로직을 작성한 뒤, 다른 코드와 마찬가지로 파일을 Git에 커밋한다.

4. 팀원이 브랜치를 풀어오면, 단순히 다음을 실행한다:

   alembic upgrade head

   로컬 데이터베이스가 자동으로 여러분의 데이터베이스와 동일하게 업데이트됩니다—추측도, 깨진 환경도 없습니다.

장점

• 안심 – 데이터베이스가 어떻게 진화했는지 단계별로 명확히 기록됩니다.
• “되돌리기” 버튼 – 단일 downgrade 명령으로 이전 안전 버전으로 즉시 롤백할 수 있습니다.
• 동기화 문제 해소 – “내 환경에서는 동작한다”는 고전적인 논쟁을 없애줍니다.

흔히 겪는 성장통

이러한 사소한 장애물에도 불구하고, 데이터베이스를 버전‑컨트롤하기 시작하면 이제까지 어떻게 살아왔는지 의문이 들 정도입니다.

미얀마 버전

Alembic: 당신의 Database를 위한 Git (왜 사용해야 할까) 🗄️

문제

금요일 저녁에 일주일 내내 힘들게 작성한 새로운 기능을 배포했다고 가정해 보세요. 앱이 실행되고 2분 정도 지나자마자 오류 로그가 뜨기 시작합니다.

문제는 무엇인가요? 프로덕션 데이터베이스에서 ALTER TABLE이라는 SQL 스크립트를 실행해야 하는데, 누군가가 잊어버렸습니다.

많은 개발자들이 코드 부분을 Git으로 정확히 추적하고, PR을 검토하고, 브랜치를 나누어 체계적으로 작업합니다. 하지만 데이터베이스 스키마가 되면 놀라울 정도로 복잡해질 수 있습니다.

• 기억에만 의존한다
• Slack에 쿼리를 복사‑붙여넣기 해서 보낸다
• db_update_final_v3.sql 같은 이름을 가진 파일을 사용한다

Alembic이란?

Alembic = 당신의 Database를 위한 Version Control

데이터베이스 관리자로 들어가 테이블을 직접 수동으로 수정하는 대신, Alembic을 사용해 Python Script로 어떤 변경을 할지 작성할 수 있습니다.

예시 – 사용자 인증 시스템

시간이 좀 지나고 제품 팀이 last_login_date 컬럼을 추가하고 싶어한다면…

Alembic이 없을 때

• SQL 명령을 수동으로 실행한다
• 팀의 다른 사람들도 잊어버릴 수 있어 언제 실행할지 모른다

Alembic을 사용할 때

1. 터미널에서 새로운 Migration Script을 생성

요약

• Rollback
  한 줄로 이전 안전한 상태로 즉시 되돌릴 수 있습니다 (Rollback).

• Sync 문제 방지
  “내 컴퓨터의 데이터베이스에서는 잘 동작한다”는 변명들이 완전히 사라질 것입니다.

• 어려움
  맞습니다, 모든 것이 약간의 어려움을 동반합니다.

  • 처음에는 학습할 시간을 조금 할애해야 합니다.
  • 컬럼 하나를 간단히 삭제하고 싶을 때 Alembic의 별도 문법을 학습해야 해서 작업이 더 많아질 수 있습니다.

• Multiple Head Error
  두 명의 개발자가 동시에 서로 다른 브랜치에서 새로운 마이그레이션 스크립트를 만들면, 병합 시 “multiple head” 오류가 발생합니다. 이는 Git의 병합 충돌과 동일하므로 수동으로 해결해야 합니다.

• 결론
  이런 작은 어려움들이 있긴 하지만, 데이터베이스를 버전 관리해 보면 과거에 어떻게 작업했는지 생각하게 될 것입니다.