Alembic迁移失败：列默认值非常量问题求助

核心原因 #

Alembic 1.0.11引入的SQLite默认值反射逻辑，将代码中server_default=text("DEF")的定义误判为非常量表达式，导致生成临时表的DDL时，默认值被处理成(DEF)而非'DEF'。SQLite要求字符串常量默认值必须带单引号，否则会被认定为函数/表达式，触发default value of column is not constant错误。

排查步骤 #

1. 检查自动生成的迁移脚本
   执行alembic revision --autogenerate后，打开生成的迁移文件，定位创建临时表的SQL语句，查看existing_col的默认值格式：

   • 如果是DEFAULT (DEF)，说明问题确实出在Alembic的反射逻辑将无引号的DEF识别为表达式。
   • 如果是DEFAULT 'DEF'，则需要排查pysqlcipher3的解析差异等其他环节。

2. 验证SQLAlchemy的反射结果
   编写小脚本确认现有数据库中列的默认值被反射后的格式：

   from sqlalchemy import create_engine, inspect
   
   # 替换为你的数据库连接字符串
   engine = create_engine("sqlite+pysqlcipher://your_connection_params")
   inspector = inspect(engine)
   table_cols = inspector.get_columns("your_target_table")
   
   for col in table_cols:
       if col["name"] == "existing_col":
           print(f"反射得到的默认值: {col['default']}")
   

   • 如果输出是DEF而非'DEF'，说明反射过程丢失了引号，导致后续DDL生成错误。

3. 对比不同server_default定义的行为
   临时修改代码，分别测试以下定义，观察迁移是否正常：

   • server_default=text("'DEF'")（带单引号的text）
   • server_default=literal("DEF")（使用Literal类型）
     若其中某一种能正常执行迁移，说明该定义能被Alembic正确识别为常量。

解决方案 #

方案1：修正server_default的定义（推荐）

将原代码中的text("DEF")替换为带单引号的text或直接使用literal：

from sqlalchemy import String, Column, literal, text

# 方式1：使用literal，自动处理常量格式
existing_col = Column(
    String(16),
    default="DEF",
    server_default=literal("DEF")
)

# 方式2：给text添加单引号
existing_col = Column(
    String(16),
    default="DEF",
    server_default=text("'DEF'")
)

这两种方式都能让Alembic的反射逻辑识别为字符串常量，生成符合SQLite要求的DDL。

方案2：自定义SQLite方言修正反射逻辑

如果无法修改现有列定义，可以自定义方言，在反射时自动为字符串默认值添加引号：

from sqlalchemy.dialects.sqlite.pysqlcipher import SQLiteDialect_pysqlcipher
from sqlalchemy.sql.expression import text

class FixedSQLiteDialect(SQLiteDialect_pysqlcipher):
    def reflectcolumn(self, connection, table_name, column_info, **kwargs):
        col = super().reflectcolumn(connection, table_name, column_info, **kwargs)
        # 针对字符串类型的列，检查默认值是否未带引号
        if (isinstance(col.type, String) 
            and col.server_default is not None 
            and not str(col.server_default.arg).startswith("'")):
            col.server_default = text(f"'{col.server_default.arg}'")
        return col

# 创建引擎时指定自定义方言
engine = create_engine("sqlite+pysqlcipher://your_connection_params", dialect=FixedSQLiteDialect)

方案3：手动修改迁移脚本（临时方案）

每次自动生成迁移脚本后，找到创建临时表的语句，将DEFAULT (DEF)手动修改为DEFAULT 'DEF'，再执行迁移。此方法适合临时应急，但长期维护成本高。

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