Alembic修改列类型：sqlalchemy.Text转JSON未生效问题

以下是几种常见的原因和对应的排查方向：

1. 迁移脚本未实际执行或执行失败 #

• 确认你运行了正确的Alembic升级命令：alembic upgrade head，并查看命令输出是否有报错。如果执行过程中触发了事务回滚（比如数据格式不合法），列类型不会发生变更。
• 直接登录PostgreSQL，执行SELECT column_name, data_type FROM information_schema.columns WHERE table_name = 'your_table';，确认当前列的实际类型，同时检查数据库的事务日志，看ALTER TABLE语句是否被成功执行。

2. 手动迁移脚本的类型定义错误 #

• 针对PostgreSQL，必须使用方言专属的类型定义，不能仅依赖SQLAlchemy的抽象类型：
  • 要改为JSONB：需导入from sqlalchemy.dialects.postgresql import JSONB，然后在脚本里写op.alter_column('your_table', 'your_column', type_=JSONB())
  • 要改为JSON：用sa.JSON()或者postgresql.JSON()，确保脚本里的类型映射到PostgreSQL的json类型
• 如果脚本里仅写了type_=sa.JSON()但没有正确关联到PostgreSQL的方言类型，可能生成的ALTER语句无效，导致列类型不变。

3. Alembic版本脚本存在问题 #

• 检查alembic/versions目录下对应的迁移脚本，确认upgrade()函数里确实包含了正确的ALTER COLUMN语句，比如：

  def upgrade():
      op.alter_column('your_table', 'your_column', type_=JSONB(), existing_type=sa.Text())
  

• 之前autogenerate生成的未识别变更脚本可能残留了错误状态，确保手动编写的脚本覆盖了正确的类型变更逻辑。

4. 原TEXT列数据不符合JSON格式 #

• PostgreSQL在将TEXT转换为JSON/JSONB时，要求原列的所有数据都是有效的JSON格式。如果存在无效数据，ALTER TABLE操作会失败，列类型保持不变。
• 可以手动在PostgreSQL中测试转换：

  ALTER TABLE your_table ALTER COLUMN your_column TYPE jsonb USING your_column::jsonb;
  

  如果这条语句报错，说明存在无效的JSON数据，需要先清理或修复这些数据后再执行迁移。

5. 模型定义未同步（非直接原因，但需注意） #

• 虽然这不会直接导致数据库列类型不变，但如果你的SQLAlchemy模型中该列仍定义为sa.Text()，后续的autogenerate可能会生成反向变更的脚本，同时也会误导开发时的类型判断。确保模型定义和迁移后的数据库类型一致。

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