[FastAPI] Alembic 사용법 - 초기 설정

Alembic

Alembic 은 경량 데이터베이스 마이그레이션 툴입니다. SQLAlchemy 에 호환되는 툴로서 자바 진영의 flyway와 비슷한 기능을 한다고 보시면 됩니다.

사용법

초기 설정

pip install alembic

우선 alembic 라이브러리를 설치해줍니다.

alembic init 임의파일명

# ex
alembic init alembic

init을 해줍니다.

인자로 alembic 과 관련된 파일들을 저장할 폴더명을 받습니다. 저의 경우 alembic 을 폴더명으로 사용했습니다.

새로운 폴더 하나와 파일 하나가 생깁니다.

여기서 sqlalchemy.url의 값으로 데이터베이스 주소를 입력해줘야 합니다.

ini 파일이기 때문에 정적 문자열만 입력해줄 수 있습니다.

만약 .env 파일에 저장해둔 내용을 불러오고 싶다면 alembic/env.py 파일에서 지정해줘야 합니다.

# this is the Alembic Config object, which provides
# access to the values within the .ini file in use.
config  =  context.config

config.set_main_option("sqlalchemy.url", os.getenv("DATABASE_URL"))

# Interpret the config file for Python logging.
# This line sets up loggers basically.
if  config.config_file_name  is  not  None:
    fileConfig(config.config_file_name)

# add your model's MetaData object here
# for 'autogenerate' support
# from myapp import mymodel
# target_metadata = mymodel.Base.metadata
target_metadata  =  models.Base.metadata

# other values from the config, defined by the needs of env.py,
# can be acquired:
# my_important_option = config.get_main_option("my_important_option")
# ... etc.

위는 alembic/env.py 의 내용을 수정한 부분입니다.

두 부분에 유의합니다.

1. config.set_main_option("sqlalchemy.url", os.getenv("DATABASE_URL"))
   • 데이터베이스 주소를 지정해주는 부분입니다. config._set_main_option의 두번째 인자값만 수정해주면 됩니다. 저의 경우 .env 파일의 DATABASE_URL을 가져와 사용했습니다.
2. target_metadata = models.Base.metadata
   • sqlalchemy.orm 의 declarative_base 함수를 호출한 값을 가져와 사용합니다.
   • 보통 models 모듈에 Base 라는 변수로서 저장하게 됩니다.
     • Base.metadata 의 형식으로 입력해줍니다.

마이그레이션

alembic revision --autogenerate -m 임의메시지

모든 초기 설정을 마친 후 위와 같이 입력해줍니다.

임의 메시지는 필수 입력값은 아니며 컬럼을 어떤 식으로 변경할 의도인지를 적어주는 용도로 활용할 수 있습니다.

alembic 자체가 100% 완벽한 SQL을 짜주는 것은 아니라고 합니다. 아주 적은 경우의 수지만 필요치 않은 SQL을 짜는 경우도 있다고 하니 자동 스크립트 기능으로 작성된 SQL을 확인해볼 필요가 있는데요. revision 명령어를 입력한 후 시간이 지났을 때에도 메시지를 확인함으로써 SQL 이 가지는 의도를 명확히 할 수 있습니다.

revision 을 수행해줄 경우 위와 같은 py 파일이 생성됩니다.

배정된 Revision ID은 파일명되고 사용자가 임의로 지정한 메시지는 뒤에 붙습니다.

저의 경우 test를 적어주었기 때문에 위처럼 마지막에 test 라는 문구가 입력되어있습니다.

생성된 py 파일에는 위와 같은 내용이 입력되어있습니다.

각각 다음과 같은 명령어를 사용 시 호출되는 함수들입니다.

# 지정한 RevisionID의 upgrade 함수 실행
alembic upgrade RevisionID

revision을 통해 스크립트를 생성했다면 위와 같이 upgrade 명령을 통해 적용할 수 있습니다.

# 마지막에 실행했던 Revision의 downgrade 함수 실행
alembic downgrade -1

적용한 revision을 원복하고 싶다면 위와 같이 downgrade 명령을 활용할 수 있습니다.

더 세세한 내용이 궁금하시다면 공식 문서에서 확인해보실 수 있습니다.