정정지용
기술스택 목록
데이터베이스

Alembic

프로젝트 1개에서 사용했습니다. 각 프로젝트에서 어떤 역할로 썼는지 아래에 정리했습니다.

이 기술은 무엇인가요?

SQLAlchemy 기반으로 데이터베이스 스키마 변경 이력을 버전 관리하는 마이그레이션 도구

Alembic은 SQLAlchemy 작성자가 만든 데이터베이스 마이그레이션 도구로, 테이블 구조 변경을 코드로 작성하고 버전 순서대로 적용·되돌릴 수 있게 해준다. 애플리케이션 코드는 Git으로 버전 관리하면서 정작 DB 스키마 변경은 수동 SQL로 관리되어 팀원 간 스키마가 어긋나는 문제를 해결하기 위해 만들어졌다. 각 변경 사항을 하나의 리비전 파일로 남기기 때문에, 스키마가 언제 어떻게 바뀌었는지 이력을 추적하고 여러 환경(개발/스테이징/운영)에 동일한 순서로 반영할 수 있다.

이럴 때 사용합니다

  • SQLAlchemy로 ORM 모델을 정의하는 파이썬 프로젝트에서 스키마 변경을 코드로 관리하고 싶을 때
  • 애플리케이션 기동 시 자동으로 DB 스키마를 최신 상태로 맞춰야 할 때
  • 여러 개발/운영 환경에서 동일한 순서로 스키마 변경을 재현해야 할 때
  • 스키마 변경 이력을 리뷰하고 필요 시 이전 버전으로 롤백해야 할 때

핵심 개념

Migration Script
스키마 변경 하나를 나타내는 파이썬 파일로, 변경을 적용하는 upgrade 함수와 되돌리는 downgrade 함수를 가진다.
Revision
각 마이그레이션 스크립트에 부여되는 고유 식별자이며, 이전 리비전을 가리키는 참조로 변경 순서가 체인처럼 연결된다.
Migration Chain / History
리비전들이 부모-자식 관계로 연결되어 만들어지는 순서열로, 현재 DB가 어느 리비전 상태인지 판단하는 기준이 된다.
Autogenerate
SQLAlchemy 모델 정의와 실제 DB 스키마를 비교해 차이를 감지하고 마이그레이션 스크립트 초안을 자동 생성하는 기능.
env.py
마이그레이션 실행 환경을 설정하는 스크립트로, DB 연결 정보와 모델 메타데이터를 Alembic에 연결해준다.
Upgrade / Downgrade
스키마를 다음 리비전으로 전진시키거나 이전 리비전으로 되돌리는 두 방향의 동작.

마이그레이션 생성과 적용

SQLAlchemy 모델과 DB 상태를 비교해 마이그레이션 파일을 생성하고, 이를 순서대로 적용하거나 되돌리는 기본 흐름이다.

Shell
# 초기 설정 (프로젝트 루트에 alembic.ini, migrations/ 생성)
alembic init migrations

# 모델 변경 후 마이그레이션 스크립트 자동 생성
alembic revision --autogenerate -m "add users table"

# 최신 리비전까지 스키마 적용
alembic upgrade head

# 한 단계 이전 리비전으로 되돌리기
alembic downgrade -1

처음 쓸 때 흔한 함정

  • autogenerate는 모든 변경을 완벽히 감지하지 못하므로 생성된 스크립트를 반드시 검토해야 한다
  • 여러 브랜치에서 동시에 리비전을 만들면 히스토리가 갈라져 병합 시 충돌이 발생할 수 있다
  • 앱 기동 시 자동 마이그레이션을 걸어두면 다중 인스턴스가 동시에 실행되며 경쟁 상태가 생길 수 있다

위 개요는 기술 학습을 돕기 위해 자동 생성된 일반 설명입니다. 정확한 사양과 최신 정보는 공식 문서를 확인하세요.

프로젝트별 활용 방식

위 개념이 실제 프로젝트에서 어떻게 쓰였는지 보여줍니다.

함께 사용한 기술

위 프로젝트들에서 같이 쓰인 다른 기술입니다.

DockerFastAPIGitHub ActionsgRPChttpxJinja2Next.jsPostgreSQLPyArrowPythonSQLite