Alembic含%(constraint_name)s命名约定时报约束未显式命名问题

该报错由Alembic触发：你配置的全局约束命名约定要求所有约束必须显式指定名称，但迁移操作中存在未命名的隐式约束自动生成，你之前的写法只覆盖了显式定义的约束，未覆盖到隐式生成的约束场景。

• 首先排查隐式约束来源：确认你是否在Column定义中添加了unique=True、index=True这类参数，或项目有全局配置自动给字段加索引/约束，这类逻辑会自动生成无名称的约束，就算你后续单独写了命名的UniqueConstraint也会触发冲突。
• 优先采用拆分操作的方案，不要把约束写在create_table的入参中，改成先创建表结构，再单独调用约束创建API，所有约束都显式指定名称，示例代码如下：

# 第一步：仅创建oauth2_token表的字段结构，不包含任何约束
op.create_table(
    "oauth2_token",
    sa.Column("client_id", sa.String(length=48), nullable=True),
    sa.Column("token_type", sa.String(length=40), nullable=True),
    sa.Column("access_token", sa.String(length=255), nullable=False),
    sa.Column("refresh_token", sa.String(length=255), nullable=True),
    sa.Column("scope", sa.Text(), nullable=True),
    sa.Column("revoked", sa.Boolean(), nullable=True),
    sa.Column("issued_at", sa.Integer(), nullable=False),
    sa.Column("expires_in", sa.Integer(), nullable=False),
    sa.Column("id", sa.INTEGER(), nullable=False),
    sa.Column("user_id", sa.Unicode(length=120), nullable=True),
)
# 第二步：单独创建主键约束
op.create_primary_key(
    name=op.f("pk_oauth2_token"),
    table_name="oauth2_token",
    columns=["id"]
)
# 第三步：单独创建外键约束
op.create_foreign_key(
    name=op.f("fk_oauth2_token_user_id_user"),
    source_table="oauth2_token",
    referent_table="user",
    local_cols=["user_id"],
    remote_cols=["user_id"],
    ondelete="CASCADE"
)
# 第四步：单独创建唯一约束
op.create_unique_constraint(
    name=op.f("uq_oauth2_token_access_token"),
    table_name="oauth2_token",
    columns=["access_token"]
)

• 如果修改后依然报错，检查alembic/env.py中的全局命名约定配置，确认覆盖了所有约束类型，标准配置参考：

from sqlalchemy import MetaData

convention = {
    "ix": "ix_%(column_0_label)s",
    "uq": "uq_%(table_name)s_%(column_0_name)s",
    "ck": "ck_%(table_name)s_%(constraint_name)s",
    "fk": "fk_%(table_name)s_%(column_0_name)s_%(referred_table_name)s",
    "pk": "pk_%(table_name)s"
}
target_metadata = MetaData(naming_convention=convention)

• 特殊场景排查：如果使用PostgreSQL数据库，Boolean类型的revoked字段可能会自动生成隐式检查约束，手动给该检查约束补充显式名称即可。

内容的提问来源于stack exchange，提问作者QLands - Carlos Quiros