FastAPI+SQLAlchemy项目Alembic迁移未生成users表问题

问题场景 #

构建FastAPI + SQLAlchemy + Alembic项目，尝试用Alembic替代Base.metadata.create_all(bind=engine)创建表，执行以下步骤后：

alembic init alembic # 项目目录下执行
docker-compose up --build -d # 启动服务
docker exec -ti fastapi_template_backend-api_1 bash # 进入容器

# 创建迁移
root@2c498a4c90f7:/app# alembic revision --autogenerate -m "Initial migration"
INFO  [alembic.runtime.migration] Context impl PostgresqlImpl.
INFO  [alembic.runtime.migration] Will assume transactional DDL.
INFO  [alembic.ddl.postgresql] Detected sequence named 'users_id_seq' as owned by integer column 'users(id)', assuming SERIAL and omitting
INFO  [alembic.autogenerate.compare] Detected removed table 'users'
  Generating /app/alembic/versions/07e67ff16b77_initial_migration.py ...  done

# 应用迁移
root@2c498a4c90f7:/app# alembic upgrade head
INFO  [alembic.runtime.migration] Context impl PostgresqlImpl.
INFO  [alembic.runtime.migration] Will assume transactional DDL.
INFO  [alembic.runtime.migration] Running upgrade  -> 07e67ff16b77, Initial migration

• 预期：PostgreSQL中存在users表
• 实际：仅存在alembic_version表，users表未生成

原因分析 #

核心问题是Alembic的target_metadata未加载到User模型的定义：

1. 在app/models/__init__.py中仅声明了Base = declarative_base()，但没有导入User模型，导致Base.metadata中不包含users表的元数据信息。
2. Alembic的env.py中虽然导入了Base，但这个Base的元数据是空的，无法识别需要创建users表；日志里的Detected removed table 'users'是因为之前可能通过Base.metadata.create_all创建过表，Alembic对比空元数据后误判为需要删除该表。

解决步骤 #

1. 修正模型导入，让Base元数据包含User表 #

修改app/models/__init__.py，导入User模型：

from sqlalchemy.ext.declarative import declarative_base
Base = declarative_base()

# 导入所有模型，确保Base.metadata能识别到它们
from .users import User

2. 清理错误迁移并重新生成 #

• 删除之前生成的错误迁移文件/app/alembic/versions/07e67ff16b77_initial_migration.py（文件名根据实际情况替换）
• 进入容器重新生成迁移：

alembic revision --autogenerate -m "Initial migration with users table"

此时日志应显示Detected added table 'users'，说明Alembic正确识别到需要创建的表。

3. 重新应用迁移 #

alembic upgrade head

4. 验证结果 #

连接PostgreSQL数据库，执行\dt命令，应该能看到users表和alembic_version表。

内容的提问来源于stack exchange，提问作者mascai