Alembic은 Python에서 사용하는 데이터베이스 스키마 마이그레이션 도구입니다. 주로 SQLAlchemy와 함께 사용합니다. 공식적으로도 SQLAlchemy용 경량 데이터베이스 마이그레이션 도구로 설명됩니다. (Alembic)
쉽게 말하면:
데이터베이스 테이블 구조의 변경 이력을 Git처럼 관리하는 도구
Alembic이 필요한 이유
예를 들어 처음에는 다음과 같은 SQLAlchemy 모델이 있었다고 하겠습니다.
class User(Base):
__tablename__ = "users"
id = Column(Integer, primary_key=True)
name = Column(String(100))이 상태로 데이터베이스를 운영하다가 이메일 컬럼을 추가합니다.
class User(Base):
__tablename__ = "users"
id = Column(Integer, primary_key=True)
name = Column(String(100))
email = Column(String(200))Python 코드만 변경한다고 실제 데이터베이스의 users 테이블에 email 컬럼이 자동으로 생기지는 않습니다.
직접 SQL을 실행한다면 다음과 같이 해야 합니다.
ALTER TABLE users
ADD COLUMN email VARCHAR(200);Alembic은 이런 스키마 변경을 Python 파일로 기록하고, 여러 개발·운영 환경에 순서대로 적용할 수 있게 해줍니다.
SQLAlchemy와 Alembic의 관계
역할을 구분하면 다음과 같습니다.
| 도구 | 역할 |
|---|---|
| SQLAlchemy | Python에서 데이터베이스 조회·저장 및 모델 정의 |
| Alembic | 데이터베이스 테이블 구조의 변경 이력 관리 |
| PostgreSQL, MySQL, SQLite 등 | 실제 데이터가 저장되는 데이터베이스 |
즉, SQLAlchemy가 현재 모델 구조를 정의한다면, Alembic은 모델 구조가 시간에 따라 어떻게 변경됐는지를 관리합니다.
기본 사용 흐름
1. 설치
pip install alembicSQLAlchemy도 같이 사용한다면:
pip install sqlalchemy alembic2. 초기화
프로젝트 루트에서 실행합니다.
alembic init migrations일반적으로 다음과 같은 파일이 생성됩니다.
project/
├── alembic.ini
├── migrations/
│ ├── env.py
│ ├── script.py.mako
│ └── versions/
└── app/
└── models.pyAlembic의 env.py는 데이터베이스 연결과 SQLAlchemy 모델 메타데이터를 연결하는 핵심 설정 파일입니다. 변경 이력 파일은 보통 versions/ 아래에 저장됩니다. (Alembic)
3. 마이그레이션 파일 생성
alembic revision -m "add email to users"그러면 다음과 비슷한 파일이 만들어집니다.
def upgrade():
op.add_column(
"users",
sa.Column("email", sa.String(length=200), nullable=True)
)
def downgrade():
op.drop_column("users", "email")upgrade()는 새 버전으로 변경할 때 실행됩니다.downgrade()는 이전 버전으로 되돌릴 때 실행됩니다.
4. 데이터베이스에 적용
alembic upgrade headhead는 가장 최신 마이그레이션 버전을 의미합니다.
5. 이전 버전으로 되돌리기
한 단계 이전으로 되돌립니다.
alembic downgrade -1자동 마이그레이션 생성
SQLAlchemy 모델과 현재 데이터베이스 구조를 비교해서 마이그레이션 초안을 생성할 수도 있습니다.
alembic revision --autogenerate -m "add email column"이 명령은 모델 변경을 분석해 upgrade()와 downgrade() 코드를 생성합니다. 다만 모든 변경을 완벽히 감지하는 것은 아니므로, 생성된 파일을 개발자가 검토해야 합니다. Alembic 공식 문서도 자동 생성 기능이 감지할 수 있는 변경과 감지하지 못하는 변경을 구분해 설명합니다. (Alembic)
자주 사용하는 명령어
# Alembic 초기화
alembic init migrations
# 새 마이그레이션 파일 생성
alembic revision -m "create users table"
# 모델 변경을 감지해 자동 생성
alembic revision --autogenerate -m "add email column"
# 최신 버전으로 업데이트
alembic upgrade head
# 한 단계 이전으로 롤백
alembic downgrade -1
# 현재 DB 버전 확인
alembic current
# 전체 변경 이력 확인
alembic historyGit과 비교하면
Alembic을 Git에 비유하면 이해하기 쉽습니다.
| Git | Alembic |
|---|---|
| 소스 코드 변경 관리 | DB 스키마 변경 관리 |
| commit | revision |
| commit hash | revision ID |
| checkout 이전 커밋 | downgrade |
| 최신 커밋으로 이동 | upgrade head |
단, Alembic은 데이터 자체의 일반적인 버전 관리 도구가 아니라 주로 다음과 같은 스키마 변경을 관리합니다.
- 테이블 생성·삭제
- 컬럼 추가·삭제
- 컬럼 타입 변경
- 인덱스 생성·삭제
- 외래키와 제약조건 변경
실무에서의 위치
FastAPI나 Flask 프로젝트에서는 흔히 다음 조합으로 사용합니다.
FastAPI / Flask
↓
SQLAlchemy
↓
Alembic
↓
PostgreSQL / MySQL / SQLite예를 들어 FastAPI 프로젝트에서 모델을 변경한 뒤:
alembic revision --autogenerate -m "add user status"
alembic upgrade head를 실행하면 개발, 테스트, 스테이징, 운영 데이터베이스에 같은 구조 변경을 일관되게 적용할 수 있습니다.
0 댓글