如何配置Flask-Migrate(Alembic)识别非public数据库Schema？

以下是具体配置步骤，可解决迁移时因重复创建表导致的报错：

1. 为SQLAlchemy模型指定Schema #

每个非public Schema下的模型，必须通过__table_args__明确声明所属Schema：

from flask_sqlalchemy import SQLAlchemy

db = SQLAlchemy()

class CustomSchemaModel(db.Model):
    __tablename__ = 'custom_table'
    # 指定模型所属的自定义Schema
    __table_args__ = {'schema': 'my_custom_schema'}
    id = db.Column(db.Integer, primary_key=True)
    name = db.Column(db.String(50))

2. 修改Alembic的env.py配置 #

这是核心配置步骤，让Alembic支持多Schema扫描并自动创建Schema：
打开项目根目录下migrations/env.py文件，修改run_migrations_online函数：

def run_migrations_online():
    connectable = engine_from_config(
        config.get_section(config.config_ini_section),
        prefix='sqlalchemy.',
        poolclass=pool.NullPool,
    )

    with connectable.connect() as connection:
        # 自动创建所需的非public Schema（若不存在）
        from sqlalchemy.schema import CreateSchema
        # 替换为你的所有非public Schema列表
        required_schemas = {'my_custom_schema', 'another_schema'}
        for schema in required_schemas:
            try:
                connection.execute(CreateSchema(schema))
                connection.commit()
            except Exception:
                # Schema已存在则回滚并忽略错误
                connection.rollback()

        # 配置Alembic启用多Schema支持
        context.configure(
            connection=connection,
            target_metadata=target_metadata,
            # 关键：开启多Schema扫描功能
            include_schemas=True,
            # 可选：将迁移版本表放到指定Schema（默认是public）
            # version_table_schema='my_custom_schema'
        )

        with context.begin_transaction():
            context.run_migrations()

注意：target_metadata默认已关联Flask-SQLAlchemy的db.metadata，需确保所有模型都已在应用初始化时被导入，否则Alembic无法扫描到这些模型。

3. 修复已存在表的迁移冲突 #

如果之前已手动创建表或迁移历史存在重复记录，执行以下步骤清理：

• 先备份数据库，避免数据丢失
• 执行命令标记当前数据库为最新迁移版本：

  flask db stamp head
  

• 重新生成迁移文件：

  flask db migrate -m "add multi schema support"
  

• 检查生成的迁移文件，确认没有重复创建已存在表的语句

4. 验证配置 #

执行升级命令，确认不再出现表已存在的报错：

flask db upgrade

额外注意事项 #

• 确保数据库用户拥有创建Schema的权限（以PostgreSQL为例，需具备CREATE权限）
• 后续新增Schema时，需同步更新required_schemas列表
• 若将迁移版本表放在非public Schema，需确保该Schema在执行迁移前已存在

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