Alembic - 설치 및 활용

[ Alembic 이란? ]

Alembic은 SQLAlchemy 기반의 데이터베이스 마이그레이션 도구로, 

데이터베이스 스키마를 버전 관리하고 변경 사항을 쉽게 적용하거나 되돌릴 수 있도록 해줍니다. 

 

Python으로 작성된 Alembic은 데이터베이스 테이블, 컬럼, 인덱스 등의 스키마를 코드로 정의하고, 

이를 체계적으로 관리할 수 있게 합니다.

 

주요 기능

• 스키마 변경 사항 관리: DB 스키마의 변경(예: 테이블 추가, 컬럼 수정)을 코드로 정의하고 추적
• 버전 관리: 변경 사항에 대한 마이그레이션 파일을 생성해, 특정 버전으로 롤백하거나 업데이트
• SQLAlchemy와 연동: SQLAlchemy ORM과 함께 사용하여 DB 스키마의 일관성을 유지

 

[ Alembic 설치 ]

alembic을 설치합니다.

cd /path/to/your/project
virtualenv .venv
source /path/to/your/project/.venv/bin/activate
cd /path/to/your/project/.venv/bin/

pip install alembic

 

환경파일을 생성합니다.

alembic init alembic

 

alembic.ini 파일에서 SQLAlchemy 데이터베이스 URI를 설정해야 합니다.

sqlalchemy.url = driver://user:pass@localhost/dbname

 

https://alembic.sqlalchemy.org/en/latest/front.html#installation

 

 

[ Migration  생성 ]

새 Migration 자동 생성

기존 데이터베이스에 변경 사항이 생긴 경우 새로운 마이그레이션 파일을 생성해야 합니다. 

이때 자동 생성 기능을 활용하면 Alembic이 데이터베이스의 변경 사항을 감지하여 

해당 내용을 새로운 마이그레이션 파일로 기록합니다.

alembic revision --autogenerate -m "Add Column Name"

--autogenerate:

  데이터베이스의 현재 상태와 target_metadata에 정의된 모델을 비교하여 자동으로 마이그레이션을 생성합니다.

-m "Add Column Name":

  마이그레이션에 대한 설명을 기록합니다.

 

env.py 파일 설정

자동 생성 기능을 사용하려면 env.py 파일에서 target_metadata를 설정해야 합니다. 

이를 통해 Alembic이 SQLAlchemy 모델에 접근할 수 있습니다.

env.py 파일에 다음과 같이 추가

# models.py에서 Base를 import
from models import Base
...
# target_metadata를 모델의 메타데이터로 설정
target_metadata = Base.metadata

이렇게 설정하면 Alembic이 models.py 파일에서 정의한 SQLAlchemy 모델을 기반으로 

데이터베이스의 변경 사항을 감지할 수 있습니다.

 

migration 적용

새로운 마이그레이션 파일을 생성한 후, 이를 데이터베이스에 적용하려면 다음 명령어를 실행합니다.

alembic upgrade head

upgrade head: 

  최신 버전의 마이그레이션을 데이터베이스에 적용합니다.

 

[ Alembic 활용 ]

Revision 확인

생성된 리비전 파일은 alembic/versions/ 폴더에 저장됩니다. 

이 파일에는 Alembic이 생성한 SQL 마이그레이션 코드가 포함되어 있습니다.

 

Revision 롤백

데이터베이스 스키마를 이전 상태로 롤백하려면 downgrade 명령을 사용합니다.

alembic downgrade -1

-1은 한 단계 이전 revision 롤백하겠다는 의미입니다.

 

History 확인

지금까지 생성된 리비전의 히스토리를 확인하여 모든 마이그레이션 기록을 볼 수 있습니다.

alembic history

 

현재 Revision 확인

현재 데이터베이스가 어떤 리비전에 있는지 확인하려면 다음 명령어를 사용합니다.

alembic current

현재 데이터베이스의 revision 상태를 나타내며, 데이터베이스가 최신 상태인지 확인하는 데 유용합니다.

 

Revision 간 이동

특정 리비전으로 이동하고자 할 때는 해당 리비전의 ID를 명시하여 이동할 수 있습니다.

alembic upgrade [revision_id]

[revision_id]에는 원하는 리비전의 ID를 입력합니다.

Alembic은 이 리비전까지의 모든 마이그레이션을 순차적으로 수행합니다.

 

Revision 삭제

실수로 생성한 리비전을 삭제하려면 해당 revision 파일을 삭제하고,

데이터베이스의 alembic_version 테이블에서 해당 revision ID를 제거해야 합니다.

 

Migration Script 예제

"""create account table

Revision ID: 1975ea83b712
Revises:
Create Date: 2011-11-08 11:40:27.089406

"""

# revision identifiers, used by Alembic.
revision = 'ae1027a6acf'
down_revision = '1975ea83b712'

from alembic import op
import sqlalchemy as sa

def upgrade():
    op.create_table(
        'account',
        sa.Column('id', sa.Integer, primary_key=True),
        sa.Column('name', sa.String(50), nullable=False),
        sa.Column('description', sa.Unicode(200)),
    )

def downgrade():
    op.drop_table('account')