database-migration

database-migration 技能概览

database-migration 技能能帮你做什么

database-migration 技能适合用于规划和生成数据库 schema 变更与数据迁移工作，覆盖常见 ORM 和 SQL 工作流，尤其强调回滚安全与零停机发布。它最适合那些不只是“写个 migration”这么简单的场景：比如变更会影响线上生产数据、需要分阶段发布，或者必须适配 Sequelize、TypeORM 这类特定迁移框架时。

谁适合使用这个 database-migration 技能

最适合的用户包括数据库工程团队、后端工程师、平台工程师，以及依赖 AI 辅助开发、但需要迁移结果具备运维可落地性的开发者，而不只是语法上能跑通。如果你要修改表结构、回填数据、安全重命名列，或在不同 ORM 模式之间迁移，这个技能相比空白提示词，能给模型一个更稳妥的默认工作框架。

它最擅长解决的任务是什么

当你的真实目标是产出一套可以真正执行的迁移方案时，就应该使用 database-migration 技能：包括 migration 文件、分阶段 rollout 步骤、回滚路径，以及数据转换相关考虑。它的核心价值不只是生成代码，而是帮助你减少在执行顺序、兼容窗口和失败恢复上的拍脑袋决策。

相比普通编码提示词，它的主要差异是什么

相比一般提示词，这个 database-migration 技能更明确地围绕以下内容进行设计：

• 具备 ORM 语境的 migration 示例
• 明确的 up 和 down 模式
• 零停机迁移思路
• 结构变更与数据变更结合的工作流
• 将回滚流程作为一等要求

因此，相比泛泛的“生成 SQL”请求，它更适合处理生产环境变更。

哪些内容在范围内，哪些不在

当前这个技能最强的部分是迁移模式与示例结构，尤其是 Sequelize 和 TypeORM。它在仓库级自动化、校验脚本和决策规则方面相对较弱，因为技能目录里只暴露了 SKILL.md。这意味着它很适合做迁移方案指导和草稿生成，但如果你想获得可靠结果，仍然需要补充自己的技术栈细节、约束条件和部署模型。

如何使用 database-migration 技能

database-migration 技能的安装上下文

如果你使用的是这个仓库里的 Skills 系统，可以先从仓库安装该技能，再在已能访问你代码库和 schema 上下文的 agent 会话中调用。典型安装方式如下：

npx skills add https://github.com/wshobson/agents --skill database-migration

由于这个技能主要以单个 SKILL.md 形式提供，其价值很大程度上取决于你如何组织请求，以及你提供了多少 schema 上下文。

使用前先读这个文件

建议先看：

• plugins/framework-migration/skills/database-migration/SKILL.md

由于这个技能没有额外可见的 rules/、resources/ 或脚本支持，因此不需要做很长的仓库阅读准备。更实用的阅读路径是：先看 SKILL.md，然后迅速切到你自己的 schema 文件、ORM 配置和现有 migration 历史。

让技能发挥效果，需要提供哪些输入

当你提供以下信息时，database-migration 技能的表现会明显更好：

• 当前使用的 ORM 或迁移工具：Sequelize、TypeORM、Prisma、原生 SQL 等
• 当前 schema 或 model 定义
• 目标 schema 变更
• 是否需要数据回填
• 表规模或流量敏感度
• 可接受的停机程度
• 对回滚的要求
• 目标数据库引擎：PostgreSQL、MySQL 等
• 部署方式：一次性、分阶段、blue/green、canary

如果缺少这些信息，模型虽然可能给出“看起来没问题”的 migration，但在生产环境里未必安全。

如何把模糊目标改写成高质量的 database-migration 提示词

弱提示词：

Create a migration to rename a column.

更强的提示词：

Use the database-migration skill. We use TypeORM with PostgreSQL.
Current table: users(id, full_name, created_at).
Goal: replace full_name with first_name and last_name.
Constraints: production table has 20M rows, cannot block writes, rollout must be zero-downtime, app and migration may be deployed separately.
Need:
1. phased migration plan
2. TypeORM migration files
3. data backfill strategy
4. rollback plan
5. application compatibility notes during transition

第二种写法能让技能明确知道应选择更安全的 expand-migrate-contract 方案，而不是高风险的直接重命名。

真实迁移任务中最推荐的工作流

一个实用的 database-migration usage 流程通常是：

1. 先让模型给出迁移策略。
2. 审查风险、锁行为和回滚前提。
3. 再要求生成对应框架下的 migration 文件。
4. 如果是分阶段 rollout，再要求补充应用层兼容改动。
5. 再要求验证查询和回滚步骤。
6. 在接近生产数据形态的 staging 环境验证后，再考虑信任输出。

这个顺序很关键，因为过早生成迁移代码，往往会把错误的发布模型直接固化进去。

这个技能最擅长的 ORM 模式

从仓库可见内容来看，它明确给出了以下示例：

• Sequelize migrations
• TypeORM migrations

说明中虽然提到了更广泛的 ORM / 平台迁移用途，但当前可见示例最扎实的还是这两个生态。如果你使用其他技术栈，最好明确要求模型把同样的迁移意图翻译到你的工具链里，而不要默认它已经有同等深度的内建支持。

什么时候要明确提出零停机要求

不要假设模型一定会自动优先考虑在线迁移安全。只要存在以下情况，就应当直接写明：

• 大表
• 高写入量
• 应用与数据库独立部署
• 列重命名或类型变更
• 热路径上的数据回填
• 生产流量下的约束调整

对于面向数据库工程团队的 database-migration 使用场景，这通常就是“玩具答案”和“可上线方案”之间的分水岭。

使用这个技能时，应该要求它输出什么

如果你想提高可用性，最好让 database-migration 技能返回的是一整套内容，而不只是一个文件：

• migration 代码
• rollout 顺序
• rollback 顺序
• 数据回填逻辑
• 假设与风险
• 验证清单
• 迁移后的清理步骤

这样可以避免那些隐藏但关键的运维工作被遗漏。

对直接破坏性变更的实用提醒

这个技能最适合用来避免以下这类不安全的一步到位操作：

• 立即删除旧列
• 在无兼容层的情况下直接原地重命名热点列
• 没有转换策略就直接改类型
• 在回填前就加非空约束
• 未评估锁影响就重写大表

如果你的第一版输出里出现了这些生产路径上的高风险操作，应当继续要求它改为分阶段方案。

database-migration 技能常见问题

这个 database-migration 技能只适用于 ORM migration 吗

不是。这个技能面向的是跨 ORM 和平台的数据库 schema 与数据迁移。实际使用中，当前可见示例确实偏 ORM，尤其是 Sequelize 和 TypeORM，所以如果你想得到最好结果，应该明确说明自己的技术栈，并在需要时要求输出 SQL 或对应框架版本的实现。

database-migration 技能适合新手吗

适合，但有限制。它之所以对新手友好，是因为示例比较具体；但它默认你至少具备判断迁移方案是否具备运维安全性的能力。新手可以用它来起草 migration 文件和 rollout 计划，但在经过审查前，不应把第一版答案直接当成可上生产的方案。

什么情况下不该使用 database-migration

如果你的任务只是纯概念讨论，而不是实际执行 schema / 数据变更，那就没必要用这个技能。另一个不太适合的场景是：你希望仅凭仓库本身就获得完整的环境级校验能力——因为这个技能暴露出来的目录中，并没有附带额外脚本、规则或测试 harness。

它为什么比直接让 AI 写 SQL 更好

database-migration guide 的价值在于，它把任务框定在“迁移生命周期”上，而不仅仅是语法正确。普通 SQL 提示词往往会漏掉回滚、兼容窗口、分阶段回填，以及 ORM 的 migration 约定。当部署安全性和代码正确性同样重要时，这个技能明显更合适。

它支持零停机部署吗

支持，这正是它比较明确的目标场景之一。但你仍然需要说明“零停机”在你的环境里具体意味着什么。这个词本身太宽泛，模型需要知道你的部署顺序、读写流量形态以及兼容性约束。

如何提升 database-migration 技能效果

同时提供 schema diff 和运行约束

想最快提升 database-migration 输出质量，最有效的方法是把 schema 变更和运行时约束一起给出来。例如：

Current: orders.status VARCHAR nullable
Target: orders.status ENUM not null
DB: PostgreSQL
Rows: 80M
Traffic: constant writes
Requirement: no downtime, rollback available, deploy app separately

这样会促使模型偏向分阶段迁移设计，而不是简单粗暴地给出一条 alter 语句。

安全性重要时，明确要求 expand-migrate-contract

如果第一版草稿看起来过于破坏性，就直接要求它输出 expand-migrate-contract 方案。以下场景通常都会因此明显改善：

• 重命名
• 类型转换
• 引入非空约束
• 拆表
• 反规范化或规范化调整

这是提升 database-migration usage 效果时最稳定、最可靠的方法之一。

在第一轮回复里就要求验证与回滚

一个常见失败模式是：up migration 写得没问题，但 down 很弱，甚至不现实。你可以通过直接要求以下内容来改善：

• 回滚条件
• 数据丢失风险提示
• 验证查询
• 每个阶段完成后的成功标准

这样可以迫使模型从一开始就考虑可逆性。

提供你仓库中现有的 migration 风格

如果你的项目已经形成了 migration 约定，可以贴出一到两个具有代表性的文件，并要求技能按该风格生成。这会显著改善命名方式、事务处理、时间戳风格以及框架惯用法。对于 Sequelize 和 TypeORM 尤其有帮助，因为很多团队都会在框架默认约定之外形成自己的本地规范。

迭代时不要只盯代码正确性，也要追问锁风险

拿到第一版输出后，继续追问下面这类问题：

• 哪些步骤可能锁表？
• 哪些步骤可以在持续写入时执行？
• 哪些步骤应该拆到不同 deploy 中？
• 哪一部分在回填后变得不可逆？
• rollout 期间应该监控什么？

很多时候，database-migration 技能真正对数据库工程工作产生价值，就是从这里开始的，而不是停留在生成样板代码。

留意这些常见失败模式

如果生成的 migration 出现以下问题，就要提高警惕：

• 默认表很小
• 没有回滚方案
• 过早删除旧字段
• 把 schema 变更和大规模回填合并成一个高风险步骤
• 忽略迁移期间的应用兼容性
• 使用了与你当前版本不匹配的框架语法

这些都很常见，通常说明你需要继续细化提示词，而不是说明这个技能不能用。

第一版草稿之后，怎样继续提高结果质量

把第一版答案当作“迁移提案”，而不是最终产物。然后基于以下真实信息要求技能继续修订：

• 实际表规模
• 索引情况
• 预期部署顺序
• canary 或 staging 的验证结果
• 审查中发现的错误前提

这类反馈闭环，才是让 database-migration install 与实际使用流程真正产出生产级价值的最务实方式。