mcpField
D
drizzle-safe-migrations

drizzle-safe-migrations

github.com/pedronauck数据与数据库644323 次安装1 周前更新
代码仓库

关于 drizzle-safe-migrations

drizzle-safe-migrations 是供团队安全执行 Drizzle 数据库迁移的技能，侧重可审计性与部署安全。它指导团队按顺序生成和验证结构及数据变更，并规划上线步骤。

主要功能

  1. 01区分仅结构变更与结构加数据变更
  2. 02为数据回填创建自定义迁移
  3. 03不手动修改生成的结构迁移
  4. 04检查 Drizzle 日志中的迁移顺序
  5. 05验证现有数据与全新安装场景
  6. 06记录上线风险与恢复步骤

适用场景

  1. 01在收紧约束前回填数据
  2. 02检查迁移顺序与生成的 SQL
  3. 03规划结构变更的安全部署

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/pedronauck/skills --skill drizzle-safe-migrations

安装后在 Claude Code 中输入/drizzle-safe-migrations确认已加载。

附带文件agents/openai.yamlreferences/production-playbook.md

详细介绍

Drizzle 安全迁移

概述

使用此技能以可审计、适合安全部署且符合 Drizzle 迁移模型的方式运行数据库迁移。

核心规则

  • 使用项目现有的脚本和包管理器生成架构迁移；下面的 bun run db:generate 只是示例，并非必需的脚本名称。
  • 切勿手动编辑生成的架构迁移文件。
  • 将数据回填生成为自定义迁移（bun run db:generate -- --custom --name <name>），并且只编辑该自定义 SQL 文件。
  • 在收紧约束之前，先进行数据规范化。
  • 将一次性数据修复保留在迁移历史中，不要将其隐藏在运行时逻辑中，除非紧急热修复需要临时缓解措施。

工作流

  1. 对变更进行分类：
    • schema-only：仅涉及列、表、索引或默认值变更。
    • data+schema：必须先转换旧数据，再应用新约束或默认值。
  2. 对于 data+schema，先创建自定义迁移：
    • bun run db:generate -- --custom --name <descriptive_name>
    • 添加幂等的回填 SQL。
  3. 接着生成架构迁移：
    • bun run db:generate
  4. 在 drizzle/meta/_journal.json 中验证迁移顺序：
    • 回填迁移的索引必须小于收紧约束的迁移索引。
  5. 验证生成的 SQL 和快照：
    • 回填迁移只包含预期的数据变更。
    • 架构迁移包含约束、默认值或类型变更。
  6. 针对现有数据和全新安装的情况运行负责该变更的迁移测试套件，并通过项目要求的检查。复用现有证据；无关的后端测试套件不属于额外的技能门槛。
  7. 在适用时记录重要的发布风险和恢复步骤：
    • 预期的数据转换；
    • 有锁风险的区域；
    • 回滚策略。

回填要求

  • 使用限制严格的 WHERE 子句。
  • 优先使用幂等更新（UPDATE ... WHERE status = 'legacy_value'）。
  • 不要在同一个迁移中混合无关的 DDL/DML。
  • 保持 SQL 明确且精简。

收紧约束的模式

移除允许的值（枚举/检查约束）时：

  1. 将现有行回填为有效的目标值。
  2. 将默认值更新为新值。
  3. 收紧检查/枚举约束。

对于大型表或严格的正常运行时间目标，请评估实际数据库和驱动支持的分阶段约束验证方式。PostgreSQL 的 NOT VALID / VALIDATE CONSTRAINT 仅适用于受支持的约束类型。

反模式

  • 手动编辑生成的架构迁移文件。
  • 在回填现有数据之前收紧约束。
  • 不生成迁移文件，却将一次性迁移逻辑隐藏在应用启动代码中。
  • 运行迁移时未验证 Drizzle 日志中的顺序。

参考

  • 命令模板和审查清单请参阅 references/production-playbook.md。

评论

支持 Markdown