mcpField
S
serverpod-migrations

serverpod-migrations

github.com/serverpod数据与数据库3.3k43 次安装1 天前更新
代码仓库

关于 serverpod-migrations

serverpod-migrations 是用于创建、应用和修复 Serverpod 数据库迁移的技能，说明哪些架构变更需要迁移，以及如何安全处理生成的迁移文件。

主要功能

  1. 01识别需要迁移的架构变更
  2. 02通过 Serverpod MCP 创建并应用迁移
  3. 03MCP 不可用时使用命令行
  4. 04创建并应用修复迁移
  5. 05说明安全编辑迁移 SQL 的方法

适用场景

  1. 01迁移变更后的表模型或索引
  2. 02修复发生偏移的数据库架构
  3. 03在迁移中加入数据转换

MCP 相关

当 serverpod start 正在运行且 serverpod MCP 可用时，该技能指引使用 create_migration、apply_migrations 和修复迁移工具。若 MCP 服务无法连接，则以命令行命令作为后备方案。

安装

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

$npx skills add https://github.com/serverpod/serverpod --skill serverpod-migrations

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

详细介绍

Serverpod 迁移

Serverpod 的迁移系统会为 .spy.yaml 中带有 table 的模型变更生成 SQL。迁移会在以下情况下应用：

  • 通过 serverpod MCP 调用 apply_migrations 工具时。通常是在开发期间运行着 serverpod start 时。
  • 使用 dart run bin/main.dart --apply-migrations 标志启动服务器时。通常是在生产环境运行服务器时。

何时需要迁移

  • 在 .spy.yaml 中添加、移除或重命名 table 模型或字段。
  • 更改会影响生成的外键的关系字段。
  • 添加、移除或更改索引。

如果项目未配置数据库，则不需要迁移（例如，config/<runMode>.yaml 中没有 database 部分）。

标准流程

在运行着 serverpod start 时，创建和应用迁移的标准流程会更简单。

使用运行中的 serverpod start 和 MCP 服务

当服务器通过 serverpod start 运行时，使用 serverpod MCP 执行以下操作：

  1. 使用 create_migration 工具创建迁移。
  2. 使用 apply_migrations 工具应用迁移。

如果 MCP 服务可用，始终使用它。

仅当 MCP 服务无法连接时

当服务器不是通过 serverpod start 运行时，使用 CLI 命令执行以下操作：

  1. 运行 serverpod generate，确保代码已生成。
  2. 使用 serverpod create-migration 命令创建迁移。

编辑生成的迁移

迁移目录中包含 migration.sql、definition.sql 以及 definition.json、definition_project.json 和 migration.json 文件。

创建迁移后，可以手动编辑 migration.sql。常见原因有两个：

  • 添加数据转换，让现有行也随架构一起迁移。
  • 将破坏性变更改为非破坏性变更，通过中间步骤达到相同的最终状态——例如，先添加新列，从旧列回填数据，然后删除旧列，而不是删除并重新创建。

切勿编辑目录中的其他文件。definition.sql 是完整架构，而 *.json 文件是下一次 serverpod create-migration 生成差异时使用的基准，因此更改这些文件会破坏之后创建的所有迁移。

迁移的应用方式带来以下两条规则：

  • 尚未安装任何迁移的数据库只会根据最新的 definition.sql 创建，且永远不会运行 migration.sql。现有数据库则会按顺序应用每个较新的 migration.sql。因此，编辑后的 migration.sql 最终生成的架构必须与 definition.sql 完全一致；其中的数据转换只会影响通过该版本升级的数据库。
  • 编辑已应用的迁移，不会对已运行该迁移的数据库产生任何影响。请为这些数据库创建新的迁移。

在客户端一侧（database: client 或 database: all 的模型），版本 migration.dart 中的迁移 SQL 也遵循相同规则；其定义 SQL 和 JSON 文件同样不得编辑。

修复迁移

如果数据库处于不一致状态，修复迁移可以使其恢复一致。修复迁移通过读取实时架构并将其与目标迁移版本进行差异比较来创建，因此必须能够访问数据库。

使用运行中的 serverpod start 和 MCP 服务
  1. 使用 create_repair_migration 工具创建修复迁移。可选参数：version（目标迁移版本，默认为最新版本）、tag 和 force（存在破坏性变更，或未检测到偏差时必需）。
  2. 使用 apply_migrations 工具应用修复迁移；该工具会应用所有待处理迁移和修复迁移，无需重启服务器。

如果 MCP 服务可用，始终使用它。

仅当 MCP 服务无法连接时
# Use the `--mode` flag to specify the run mode
# Use the `--version` flag to specify the target version
# Use the `--force` flag to create a migration with destructive changes
# Use the `--tag` flag to name the migration
serverpod create-repair-migration [--mode production] [--version <name>] [--force] [--tag <tag>]

通过使用 dart run bin/main.dart --apply-repair-migration 重启服务器来应用修复迁移。请让用户运行此命令。

评论

支持 Markdown