将Django模型字段从TextField迁移至ArrayField的报错问题

我之前也碰到过一模一样的迁移问题——核心矛盾在于：Django没法直接把存储JSON字符串的TextField自动转成PostgreSQL原生ArrayField，一来它不知道怎么解析JSON格式的字符串，二来PostgreSQL数组需要明确的维度/元素类型定义，直接改字段类型会触发维度缺失的报错。下面是我亲测有效的分步解决流程：

1. 先新增ArrayField字段（保留旧TextField） #

不要直接修改原字段类型，先新增一个可空的ArrayField，让初始迁移能顺利执行：

# models.py
from django.db import models
from django.contrib.postgres.fields import ArrayField

class YourTargetModel(models.Model):
    # 原字段，暂时保留不动
    legacy_json_list = models.TextField()
    # 新增的ArrayField，先设为可空（后续再调整）
    new_array_field = ArrayField(
        models.CharField(max_length=255),  # 根据你实际的元素类型调整，比如IntegerField
        null=True,
        blank=True
    )
    # 其他原有字段...

然后生成并执行第一次迁移：

python manage.py makemigrations
python manage.py migrate

2. 编写数据迁移脚本，批量转换JSON字符串到原生数组 #

接下来需要手动创建一个数据迁移，把旧字段里的JSON列表解析后写入新字段：
首先生成空迁移文件：

python manage.py makemigrations --empty your_app_name

打开生成的迁移文件，替换成以下内容（注意替换依赖的迁移名和模型名）：

from django.db import migrations
import json

def migrate_json_to_array(apps, schema_editor):
    YourTargetModel = apps.get_model('your_app_name', 'YourTargetModel')
    # 分批处理避免内存占用过高（数据量大的话可以加.iterator()）
    for instance in YourTargetModel.objects.all().iterator():
        try:
            # 解析JSON字符串为Python列表
            parsed_list = json.loads(instance.legacy_json_list)
            # 确保解析结果是列表（防止原数据格式异常）
            if isinstance(parsed_list, list):
                instance.new_array_field = parsed_list
                instance.save(update_fields=['new_array_field'])
        except json.JSONDecodeError:
            # 处理解析失败的情况：可以记录日志或设为空列表
            print(f"解析失败，实例ID: {instance.pk}，内容: {instance.legacy_json_list}")
            instance.new_array_field = []
            instance.save(update_fields=['new_array_field'])

class Migration(migrations.Migration):
    dependencies = [
        # 这里填你上一步生成的迁移文件名，比如('your_app_name', '0002_auto_20240520_1234')
        ('your_app_name', '0002_new_array_field'),
    ]

    operations = [
        migrations.RunPython(migrate_json_to_array),
    ]

执行数据迁移：

python manage.py migrate

3. 替换旧字段（可选，按需操作） #

等数据验证无误后，就可以删除旧的TextField，并把新字段重命名为原字段名：
修改models.py：

class YourTargetModel(models.Model):
    # 用新字段替代旧字段，移除null=True
    legacy_json_list = ArrayField(models.CharField(max_length=255))
    # 删除new_array_field字段
    # 其他原有字段...

生成并执行最终迁移：

python manage.py makemigrations
python manage.py migrate

关键注意事项 #

• 元素类型匹配：ArrayField的内部字段类型要和你JSON列表的元素类型严格对应（比如整数列表用ArrayField(models.IntegerField())），否则会触发类型错误。
• 异常兜底：一定要处理JSON解析失败的场景，避免迁移中断或数据丢失。
• 数据校验：迁移完成后抽样检查数据，确认转换前后的内容完全一致。

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