SuperAPI AI 工具集

django-migrations

编程与开发

查看项目

更新于 10-29 13:22

技能介绍

django-migrations 是一个指导开发者编写和审查 Django 迁移的技能,核心目标是让迁移在线上数据库中安全执行,避免长时间表锁、保证可逆、分离 schema 变更与数据变更、分批回填。资料默认以 PostgreSQL 为前提,如果项目使用 MySQL,则需要针对每个操作对照 MySQL 的在线 DDL 规则。

用途与总体思路 资料强调,一个在只有 50 行的开发库上看起来没问题的迁移,放到一千万行的生产表上可能锁表数分钟。因此该技能建议在生成迁移后先阅读实际 SQL,评估表规模,再决定每个操作是否安全。

第一步:生成后阅读 SQL 使用 python manage.py makemigrations <app> 生成迁移,再用 python manage.py sqlmigrate <app> <migration_number> 查看实际执行的 SQL。资料指出,Python 代码看起来无害的频率远高于 SQL 看起来无害,因此必须阅读 sqlmigrate 输出。同时应向开发者询问被修改表的粗略行数,或在预发布库上检查;约 10 万行以下时,后续多数规则可以放宽,但应明确说明。

第二步:逐项检查操作 资料给出了一张操作安全性对照表:新增可空字段是安全的;新增带常量默认值的字段在 PostgreSQL 11+ 上安全且不重写表,建议使用 db_default=(Django 5.0+)让默认值也存在于数据库中;新增无默认值的 NOT NULL 字段会失败或锁表,应先加可空字段、回填、再加 NOT NULL;把已有列改为 NOT NULL 会在排他锁下全表扫描,建议先用 CHECK (col IS NOT NULL) NOT VALID、VALIDATE CONSTRAINT、SET NOT NULL(PostgreSQL 12+ 可跳过扫描)、再删除检查,并使用带反向 SQL 的 RunSQL;新增索引会阻塞写入,应使用 django.contrib.postgres.operations 中的 AddIndexConcurrently 并设置 atomic = False;删除索引也会阻塞,应使用 RemoveIndexConcurrently 并设置 atomic = False;新增唯一约束会阻塞且遇重复数据失败,应先检查重复,再并发创建唯一索引后附加约束;为大表新增外键会在锁下验证所有行,可用 db_constraint=False 添加,或先加 NOT VALID 约束再通过 RunSQL 验证;重命名字段或模型会破坏部署过程中运行的代码,应使用 expand/contract 安全变更;删除字段也会破坏部署中的代码,应先移除使用,再用 SeparateDatabaseAndState 从状态中移除,在后续版本删除列;修改字段类型通常会重写表,应采用新列加回填再加切换的方式;仅修改 choices、help_text、verbose_name 的 AlterField 不产生 SQL,但仍应检查 sqlmigrate。对于有风险的 DDL,应设置 lock_timeout,让迁移快速失败而不是把后续所有查询排队。

第三步:数据迁移 数据迁移应与 schema 变更分离,绝不在同一个迁移中混合 DDL 和回填。应使用 apps.get_model("app", "Model") 而不是直接导入模型。回填必须分批,一次更新五百万行会持有锁并膨胀 WAL。资料给出了一个使用 RunPython、atomic = False 和每批 1000 条的分批回填示例。非常大规模的回填(数小时)应放在部署后运行的管理命令或 Celery 任务中,而不是迁移中。每个 RunPython 都应有 reverse_code;当反向执行 schema 迁移已足够时,RunPython.noop 可以接受,但要在注释中说明。

第四步:可逆性与历史 应在本地双向运行迁移,先 migrate <app> <previous> 再 migrate <app>。绝不要编辑已在任何共享环境运行过的迁移,应编写新迁移。合并后出现冲突迁移时使用 makemigrations --merge,并检查合并迁移没有掩盖真实的顺序问题。只有在团队同意时才压缩迁移,且不要压缩其他仓库或环境尚未应用的迁移。

第五步:CI 与部署注意事项 python manage.py makemigrations --check --dry-run 应通过,即没有缺失的迁移。在 PR 描述中应说明涉及的表、行数、预期锁行为、是否必须在代码变更之前或之后部署,以及如何回滚。

规则与限制 代码必须在部署期间同时兼容旧 schema 和新 schema,因为迁移通常在新代码上线前运行,而旧代码还会继续运行一段时间。没有 reverse_sql 的 RunSQL 不应使用,除非确实不可逆,并在迁移中说明。