Alembic 적용기

Alembic 이란?

Alembic은 SQLAlchemy ORM과 함께 사용하는 데이터베이스 마이그레이션 도구다.
DB 스키마(테이블 구조)의 변경 이력을 관리하는 역할을 한다.

---

기본 폴더 구조

alembic/
├── [env.py](http://env.py/)                          ← Alembic 실행 환경 설정 (DB 연결, 모델 등록)
├── script.py.mako                  ← 새 마이그레이션 파일 생성 시 사용하는 템플릿
├── alembic.ini                     ← Alembic 전역 설정 파일 (프로젝트 루트)
└── versions/                       ← 마이그레이션 파일들 (변경 이력)
	├── 1412e37519c6_create_users_sessions_messages.py  ← 1번: 초기 테이블 생성
	├── e9f6ca3bfbb0_add_refresh_token_to_users.py      ← 2번: refresh_token 컬럼 추가
	├── 63880cc901da_add_role_to_users.py               ← 3번: role 컬럼 추가
	├── 0119517cb86f_change_roleenum_human_ai.py        ← 4번: RoleEnum 값 변경
	├── 5f69628aa33d_add_approval_status_to_users.py   ← 5번: approval_status 추가
	└── f6d6325672ec_add_name_to_users.py              ← 6번: name 컬럼 추가

---

대표적인 함수

각 마이그레이션 파일은 두 가지 함수를 가진다.

upgrade()

DB에 변경사항을 적용한다.
→ 컬럼 추가, 테이블 생성, 타입 변경 등

downgrade()

변경사항을 이전 상태로 롤백한다.

각 파일은 revision → down_revision 체인으로 순서가 연결되어 있어,
Alembic이 어떤 순서로 적용할지 파악할 수 있다.

---

자주 사용하는 명령어

현재 적용된 버전 확인

alembic current

최신 버전으로 마이그레이션 적용

alembic upgrade head

모델 변경 후 새 마이그레이션 파일 자동 생성

alembic revision --autogenerate -m "add_column_xxx"

한 단계 롤백

alembic downgrade -1

---

alembic revision 옵션 정리

기본 옵션

옵션	설명	예시
-m "메시지"	마이그레이션 설명 (파일명에 포함됨)	-m "add_phone_to_users"
--autogenerate	모델과 DB를 비교해서 변경사항 자동 생성	--autogenerate
--rev-id	revision ID 직접 지정 (기본은 랜덤 해시)	--rev-id 0001
--branch-label	브랜치 이름 붙이기 (멀티 브랜치 관리 시)	--branch-label myfeature
--depends-on	특정 revision 이후에 실행되도록 의존성 지정	--depends-on abc123
--head	어떤 head 다음에 붙일지 지정	--head base
--splice	head가 아닌 중간 revision에 붙일 때 사용	--splice

자주 쓰는 조합

# 가장 일반적인 사용 (모델 변경 후)
alembic revision --autogenerate -m "add_phone_to_users"

# 빈 마이그레이션 파일 생성 (수동 작성 시)
alembic revision -m "manual_data_migration"

# revision ID를 읽기 쉽게 직접 지정
alembic revision --autogenerate -m "add_phone" --rev-id 0007

revision vs upgrade 차이

alembic revision --autogenerate -m "..."
└→ versions/ 폴더에 .py 파일만 생성 (DB는 아직 변경되지 않음)
alembic upgrade head
└→ 생성된 파일을 실제 DB에 적용

파일 생성과 DB 적용은 별개다.revision만 실행하면 DB는 그대로 유지된다.

---

주의사항

• -autogenerate는 SQLAlchemy 모델과 현재 DB 상태를 비교해서 차이점을 파일로 만들어준다.
  단, 아래 경우는 자동 감지가 되지 않는다.
• 컬럼 이름 변경 (삭제 + 추가로 인식함)
• 커스텀 타입 변경
• 저장 프로시저, 트리거