Sentry 如何生成并通过安全迁移检查的 Django 数据库迁移【免费下载链接】sentryDeveloper-first error tracking and performance monitoring项目地址: https://gitcode.com/GitHub_Trending/sen/sentry在 Sentry 仓库里修改 Django 模型之后你需要生成迁移文件并且它必须能通过 Sentry 迁移框架的安全检查。Sentry 的迁移不是普通的 Django 迁移仓库中的迁移文件继承自CheckedMigration见 src/sentry/new_migrations/migrations.py该类的checked属性默认为Trueapply()时会把schema_editor.safe置为True并对每个操作执行validate_operation也就是说安全检查在迁移应用apply时触发。本文给出一条完整路径用sentry django makemigrations生成迁移按检查规则修正字段写法用sqlmigrate核对 SQL再本地执行migrate触发安全检查最后处理migrations_lockfile.txt的合并冲突。Sentry 的安全检查会拦什么先理解检查机制后面每一步验证才有判断依据。核心实现在 src/sentry/new_migrations/migrations.pyCheckedMigration默认atomic False避免长操作如数据回填持锁直到提交。checked True时启用安全检查。源码注释明确可以设为False禁用安全检查但不要在没有owners-migrations团队批准的情况下这样做。validate_operation会递归检查operations包括SeparateDatabaseAndState内部的操作。直接使用RunSQL会抛出UnsafeOperationException报错信息为源码原文Using RunSQL is unsafe because our migrations safety framework cant detect problems with the migration, and doesnt apply timeout and statement locks. Use SafeRunSQL instead, and get approval from owners-migrations to make sure that its safe.所以自定义 SQL 必须使用SafeRunSQL。迁移文件本身需要继承CheckedMigration仓库中的示例见 fixtures/safe_migrations_apps/bad_flow_add_column_with_default_app/migrations/0001_initial.pyfrom sentry.new_migrations.migrations import CheckedMigration class Migration(CheckedMigration): initial True dependencies [] operations [ migrations.CreateModel( nameTestTable, fields[(id, models.AutoField(...))], ), ]生成迁移Sentry 用sentry django管理命令入口生成迁移完整规范见 .agents/skills/generate-migration/SKILL.mdsentry django makemigrations app_name注意仓库自定义的makemigrations命令src/sentry/management/commands/makemigrations.py要求必须命名迁移否则会提示并直接返回Please name your migrations using -n migration_name. For example, -n backfill_my_new_table因此实际执行的命令应带上-n把migration_name换成描述性名称sentry django makemigrations app_name -n migration_name两个变体sentry django makemigrations # 基于模型变更自动为所有 app 生成 sentry django makemigrations app_name --empty # 生成空迁移用于数据迁移或自定义操作生成后的必做检查来自generate-migration技能文档如果新增了模型确认它已导入该 app 的__init__.py人工审查生成的迁移内容是否正确用sqlmigrate核对 SQL见下文本地应用迁移让安全检查在 CI 之前先跑一遍。另外makemigrations每次运行都会重新生成 migrations_lockfile.txt它按 app 记录最新迁移名用于让 Git 在有人抢先提交了迁移时检测到合并冲突。让迁移通过检查的字段写法仓库自带一组fixtures/safe_migrations_apps/下的示例 app演示会被拦截和能通过两种写法。以给表加一列为例会被拦截的迁移 0002_add_field_default.py 写的是operations [ migrations.AddField( model_nametesttable, namefield, fieldmodels.IntegerField(default0), ), ]而能通过检查的 0002_add_field_notnull_db_default.py 写的是operations [ migrations.AddField( model_nametesttable, namefield, fieldmodels.IntegerField(db_default0), ), ]区别只有一个关键字db_default。对应规则来自generate-migration技能文档有默认值的列用db_defaultvalue不要写defaultvalue可空列nullTrue非空列not null必须设置db_default。其他与检查直接相关的规则大表加索引时在迁移上设置is_post_deployment True因为索引创建可能超过 5 秒超时不要在 Postgres 里重命名列或表改用db_column或Meta.db_table保留旧名重命名会被安全检查判定为 unsafe手动编辑已生成的迁移时例如把DeleteModel换成SafeDeleteModel保留自动生成的is_post_deployment注释块它记录了非显性的标记含义。用 sqlmigrate 核对生成的 SQL在应用之前先确认迁移会执行哪些 SQLsentry django sqlmigrate app_name migration_nameapp_name是迁移所属的 Django app 标签migration_name是生成或命名时的迁移文件前缀。输出应与你在迁移文件里看到的 operations 一一对应发现多余或缺失的语句时回到迁移文件修正后重新核对。本地验证migrate 触发安全检查generate-migration技能文档明确说明Sentry 的迁移框架在应用时运行安全检查所以本地先执行sentry django migrate app_name如果迁移包含不安全操作缺db_default的非空列、未走SafeRunSQL的RunSQL、直接删表删列等这一步会抛出UnsafeOperationException在 CI 之前暴露问题。仓库集成测试 tests/sentry/db/postgres/schema/safe_migrations/integration/test_migrations.py 里固定了一组真实报错消息可以对照判断自己遇到的是哪类拦截例如摘自该测试文件Adding TestTable.field as a not null column with no default is unsafe. Provide a default using db_default. Altering the type of column TestTable.field in this way is unsafe Renaming table for model NewTable from ... is unsafe Renaming column TestTable.field to new_field is unsafe Deleting the TestTable model is unsafe. Removing the TestTable.field field is unsafe删列、删表的完整流程不能一步到位必须分两阶段、两个 PR第二阶段叠在第一阶段之上且第一阶段部署后才能合并第二阶段具体写法见 generate-migration/SKILL.md 中 Deleting Columns 和 Removing a Model 两节此处不展开。本地数据库状态异常时仓库AGENTS.md指向make reset-db重置数据库。想直接验证检查机制本身也可以跑上述集成测试文件仓库 Makefile 中的 pytest 调用形式为python3 -b -m pytest tests/... --reuse-db据此可用python3 -b -m pytest tests/sentry/db/postgres/schema/safe_migrations/integration/test_migrations.py --reuse-db这些测试会逐个应用 fixtures 中的 bad/good 迁移断言哪些会抛UnsafeOperationException、哪些能正常执行完。处理 migrations_lockfile.txt 冲突makemigrations每次都会重写 migrations_lockfile.txt。文件头部注释说明了冲突含义如果这个文件产生合并冲突说明 master 上有人提交了一个你分支里不存在的迁移。处理方式来自generate-migration技能文档bin/update-migration migration_name该脚本会重命名你的迁移、更新依赖并修复 lockfile文件注释给出的另一条路径是 rebase 到最新 master 后重新生成迁移。另外自定义命令的--check模式会校验各 app 的最新迁移与 lockfile 是否一致不一致时以退出码 2 结束供 CI 使用。边界与限制CheckedMigration的checked False禁用安全检查需要owners-migrations团队批准源码注释明确不建议擅自设置使用原始RunSQL会直接失败必须换SafeRunSQL并取得owners-migrations批准is_post_deployment True仅针对大表上索引创建可能超过 5 秒超时的场景普通迁移不需要。完成的标志是sentry django sqlmigrate输出的 SQL 与预期一致sentry django migrate app_name在本地执行完毕且未抛出UnsafeOperationExceptionmigrations_lockfile.txt随迁移一起更新进你的分支。【免费下载链接】sentryDeveloper-first error tracking and performance monitoring项目地址: https://gitcode.com/GitHub_Trending/sen/sentry创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考