Alembic autogenerate가 no changes detected를 내는 이유

Alembic autogenerate가 no changes detected를 낸다는 것은 Alembic이 비교한 DB schema와 SQLAlchemy metadata 사이에서 생성할 migration 차이를 찾지 못했다는 뜻입니다. 실제로 변경이 없을 수도 있지만, 설정 문제로 모델을 못 본 경우도 많습니다.

핵심은 Alembic이 어떤 DB와 어떤 metadata를 비교하고 있는지 확인하는 것입니다. 모델 파일을 고쳤는데도 no changes detected가 나온다면 env.py, target_metadata, import 경로부터 봐야 합니다.

Alembic autogenerate는 무엇을 비교할까

autogenerate는 파이썬 모델 파일 자체를 마법처럼 읽는 기능이 아닙니다. 실행 중인 env.py에서 연결한 데이터베이스의 현재 schema와, target_metadata에 들어온 SQLAlchemy MetaData를 비교합니다.

그래서 모델 클래스를 추가했더라도 그 모델이 Base.metadata에 등록되지 않았거나 env.py에서 import되지 않으면 Alembic은 변경을 볼 수 없습니다.

가장 흔한 원인: target_metadata가 None

# alembic/env.py
from app.db.base import Base
from app.models import user, post  # 모델 import가 필요할 수 있다

target_metadata = Base.metadata

# alembic/env.py
from app.db.base import Base
from app.models import user, post  # 모델 import가 필요할 수 있다

target_metadata = Base.metadata

공식 템플릿에는 target_metadata = None 형태가 들어 있습니다. autogenerate를 쓰려면 애플리케이션의 Base.metadata로 바꿔야 합니다.

모델 import 누락

SQLAlchemy declarative model은 import되어야 metadata에 테이블 정보가 등록됩니다. Base는 가져왔지만 실제 모델 모듈을 아무도 import하지 않으면 metadata가 비어 있을 수 있습니다.

• app.models 패키지의 __init__.py에서 모델을 모아 import한다
• env.py에서 필요한 모델 모듈을 명시적으로 import한다
• 순환 import가 생기지 않도록 db base와 model import 방향을 정리한다

DB URL이 다른 곳을 보고 있는 경우

개발 DB를 바꿨다고 생각했지만 alembic.ini나 env.py는 테스트 DB 또는 로컬 sqlite 파일을 보고 있을 수 있습니다. 이 경우 실제로 비교 대상 DB에는 이미 변경이 반영되어 있거나, 반대로 전혀 다른 schema와 비교하게 됩니다.

from alembic import context
from sqlalchemy import engine_from_config

config = context.config
print("alembic url:", config.get_main_option("sqlalchemy.url"))

from alembic import context
from sqlalchemy import engine_from_config

config = context.config
print("alembic url:", config.get_main_option("sqlalchemy.url"))

migration head와 실제 DB 상태

autogenerate는 현재 DB schema를 기준으로 비교합니다. migration 파일이 있다고 해서 DB가 그 상태라는 뜻은 아닙니다. 먼저 alembic current, alembic history, alembic upgrade head 흐름을 확인해야 합니다.

autogenerate가 자동으로 못 잡는 변화도 있다

Alembic 문서는 autogenerate가 완벽하지 않으며 생성된 migration을 사람이 검토하고 수정해야 한다고 설명합니다. 일부 이름 변경, 복잡한 constraint, 데이터 이동은 자동 생성 결과만 믿으면 위험합니다.

점검 순서

1. env.py의 target_metadata가 Base.metadata인지 확인한다
2. 모든 model 모듈이 import되는지 확인한다
3. metadata.tables에 기대한 테이블이 들어 있는지 출력해본다
4. alembic이 바라보는 DB URL을 확인한다
5. 현재 DB revision과 migration head를 확인한다
6. 자동 생성된 migration은 반드시 사람이 검토한다

정리

Alembic autogenerate의 no changes detected는 변경이 없다는 뜻일 수도 있지만, Alembic이 모델을 못 보고 있다는 신호일 수도 있습니다. target_metadata, 모델 import, DB URL, 현재 revision을 순서대로 확인하면 대부분 원인을 좁힐 수 있습니다.

공식 기준은 Alembic autogenerate 문서를 먼저 보면 됩니다. SQLAlchemy 비동기 오류 흐름은 MissingGreenlet 글과 연결해 읽기 좋습니다.