Python SQLAlchemy Alembic多模型迁移出现重复表键错误如何解决

• Flask-SQLAlchemy 实例化的db对象自带全局唯一的MetaData容器，所有继承db.Model的模型都会自动将自身表结构注册到db.metadata中，单个模型的.metadata属性默认就是指向这个全局对象的。
• 你将target_metadata配置为MetaData对象列表的形式，会让 Alembic 逐一扫描列表中所有MetaData的表定义。如果列表中存在多个包含相同表名的MetaData实例、或是同一个MetaData实例被重复加入列表，扫描时就会检测到重复表键，触发对应的ValueError报错。

1. 修改src/models/__init__.py配置，直接导出全局db.metadata，无需单独收集单个模型的metadata：

from flask_sqlalchemy import SQLAlchemy
db = SQLAlchemy()

# 导入所有需要加入迁移的模型，确保完成注册
from .Model1 import Model1
from .Model2 import Model2
from .Model3 import Model3

# 直接导出全局唯一MetaData对象，不要用列表封装
MyMetadata = db.metadata

2. 修改migrations/env.py配置，直接赋值即可：

from src.models import MyMetadata
target_metadata = MyMetadata

• 必须在src/models/__init__.py中显式导入所有需要生成迁移的模型类，否则模型不会被注册到db.metadata，Alembic 自动生成迁移时会识别不到对应表。
• 所有模型统一继承db.Model即可，不要为单个模型单独创建独立的MetaData实例，避免出现多套MetaData包含重复表名的情况。
• 仅当你需要维护多套完全独立、表名无重复的模型迁移体系时，才需要使用MetaData列表的配置形式。

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