SQLAlchemy + alembic 마이그레이션

• 언어 : Python
• 프레임워크 : FastAPI
• ORM : SQLAlchemy
• 마이그레이션 툴 : alembic
• alembic documentaion : https://alembic.sqlalchemy.org/en/latest/index.html

1. SQLAlchemy

• SQLAlchemy 의 경우 migration 기능을 포함하지 않으며, Alembic 이라는 별도 패키지를 함께 사용해야합니다.

2. Alembic

• transsactional DDL 을 지원합니다.
• 그래서 Database Scema가 생성되기 전에는 Database 변경이 일어나지 않습니다.
  • 마이그레이션 명령어를 입력하면 upgrade & downgrade function과 함께 script 파일이 생성됩니다.
  • 해당 파일에는 revision_id를 함께 생성합니다. 이 revision_id를 기준으로 DB update가 진행 됩니다.
  • 또한, 버전 테이블이 존재하여 마이그레이션 버전이 테이블에 기록되기 때문에 중복 마이그레이션을 확인 할 수 있습니다.
    원리

3. 구현

3-1. alembic 라이브러리 설치

pip install alembic 

3-2. alembic init 생성

alembic init [프로젝트 명]

ex) alembic init project

위의 명렁어를 입력하면 아래 구조의 디렉토리와 alembic.ini 파일이 생성됩니다.

3-3. alembic 파일 구조

1. 각자의 루트 파일 명

• alembic 소스트리의 루트파일이며, 이름은 alembic init [프로젝트 명] 해당 부분에 입력한 프로젝트 명으로 생성이 됩니다.

2. env.py

• 마이그레이션 시 실행되는 python script 파일입니다. SQLAlchemy 엔진 구성 및 데이터베이스와의 연결을 설정하는 파일입니다.
• 해당 파일에서 마이그레이션 실행 방식을 지정할 수 있습니다.

3. script.py.mako

• mako 템플릿이며, 해당 파일 기준으로 마이그레이션 스크립트 파일이 생성됩니다.
• upgrade() 와 downgrade() 를 포함한 기본 구조의 형태를 가지며 아래와 같이 함수를 수정하여 사용가능합니다.
• upgrade()
  • DB 마이그레이션이 적용될 스크립트가 들어갑니다.
• downgrade()
  • DB 마이그레이션 이후 롤백 할 시에 사용되는 함수입니다.
• mako 파일을 수정했다면, 마이그레이션 스크립트 파일도 아래와 같이 생성됩니다.
  

  

4. versions

• 마이그레이션 스크립트 파일이 저장되는 디렉토리입니다.

5. alembic.ini

• alembic 스크립트가 실행될 때 바라보는 파일입니다.

3-4. 설정 파일 수정하기

1. alembic.ini

• 해당 파일에서 데이터베이스 주소를 입력해야합니다.
• 그러나 ini 파일이기 때문에, 정적 문자열만 사용가능합니다. 해당 문자열은 빈 스트링으로 둔 후 env.py 파일에서 데이터베이스 url 설정을 해줍니다.

기존
sqlalchemy.url = driver://user:pass@localhost/dbname
변경
sqlalchemy.url =

3-5. alembic env 파일 수정하기

env.py

## 1. DB URL 설정
- DB 연동을 위해 config 설정 값을 추가해줍니다.

config.set_main_option('sqlalchemy.url', '연동할 DB url 이 있는 위치를 임포트')
ex)
config.set_main_option('sqlalchemy.url', Settings.DATABASE_URL)


## 2. target_metadata 설정
- 테이블 모델이 정의된 파일을 정의해줍니다.
- 모델이 정의된 파일이 아래와 같이 여러 파일에 나뉘어져 있는 경우 env 파일 상단에 모델 파일 경로를 import 해줘야합니다.
- sqlalchemy base 경로도 import 해줍니다.

from app.db.models import *
from app.db.session import Base

target_metadata = Base.metadata

3-6. 마이그레이션 파일 생성

alembic revision --autogenerate -m "마이그레이션 파일에 대한 설명"

 > autogenerate 해당 옵션을 붙이면 SQLAlchemy 의 ORM을 이용하여 정의한 Model의 데이터를 읽어 이전 테이블 상태와 비교 후, 변경된 부분을 마이그레이션 스트립트로 작성해줍니다.

3-7. 마이그레이션 실행

alembic upgrade head

 > head 는 가장 상위의 revision으로 DB를 upgrade 합니다.