serverpod-migrations

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Serverpod Migrations

Serverpod has a migration system that generates SQL for changes to models with

table

.spy.yaml

. The migrations are applied:

When the
```
apply_migrations
```
tool is called via the
```
serverpod
```
MCP. Typically during development with a running
```
serverpod start
```
.
When the server is started with
```
dart run bin/main.dart --apply-migrations
```
flag. Typically when running the server in production.

Serverpod 拥有一套迁移系统，可为

.spy.yaml

中标记为

table

的模型变更生成 SQL。迁移的应用场景如下：

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

When migrations are needed

何时需要迁移

Added, removed, or renamed
```
table
```
models or fields in
```
.spy.yaml
```
.
Changed relation fields that alter generated foreign keys.
Added, removed, or changed indexes.

Migrations are not needed when the project has no database configured (e.g.

config/<runMode>.yaml

with no

database

section).

在
```
.spy.yaml
```
中添加、移除或重命名
```
table
```
模型或字段时。
修改关联字段导致生成的外键发生变化时。
添加、移除或修改索引时。

如果项目未配置数据库（例如

config/<runMode>.yaml

中没有

database

部分），则无需迁移。

Standard flow

标准流程

The standard flow for creating and applying migrations is simplified when a

serverpod start

is running.

当

serverpod start

运行时，创建和应用迁移的标准流程会被简化。

With a running

serverpod start

and MCP server

运行

serverpod start

并连接 MCP 服务器时

When the server is running from

serverpod start

use the

serverpod

MCP to:

Create a migration using the
```
create_migration
```
tool.
Apply the migration using the
```
apply_migrations
```
tool.

ALWAYS use the MCP server if it is available.

当服务器通过

serverpod start

运行时，使用

serverpod

MCP 执行以下操作：

使用
```
create_migration
```
工具创建迁移。
使用
```
apply_migrations
```
工具应用迁移。

如果 MCP 服务器可用，请务必使用它。

ONLY if MCP server fails to connect

仅当 MCP 服务器连接失败时

When the server is not running from

serverpod start

use the CLI commands to:

Ensure the code is generated by running
```
serverpod generate
```
.
Create a migration using the
```
serverpod create-migration
```
command.

当服务器未通过

serverpod start

运行时，使用 CLI 命令执行以下操作：

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

Editing a generated migration

编辑生成的迁移

A migration directory holds

migration.sql

definition.sql

and the

definition.json

definition_project.json

and

migration.json

files.

migration.sql

MAY be edited by hand after it is created. Two common reasons:

Adding a data transformation, so existing rows are migrated along with the schema.
Turning a destructive change into a non-destructive one, by reaching the same end state through intermediate steps — for example add the new column, backfill it from the old one, then drop the old column, instead of dropping and recreating.

Never edit the other files in the directory.

definition.sql

is the full schema, and the

*.json

files are what the next

serverpod create-migration

diffs against, so changing them corrupts every migration created afterwards.

Two rules follow from how migrations are applied:

A database that has no migrations installed is created from the latest
```
definition.sql
```
alone and never runs
```
migration.sql
```
. An existing database applies each newer
```
migration.sql
```
in order. So the schema an edited
```
migration.sql
```
ends up with must stay identical to
```
definition.sql
```
, and data transformations in it only affect databases that upgrade through that version.
Editing a migration that has already been applied does nothing to the databases that ran it. Create a new migration for those.

On the client side (models with

database: client

database: all

), the same applies to the migration SQL inside the version's

migration.dart

; its definition SQL and JSON files are equally off limits.

迁移目录包含

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 文件同样不可修改。

Repair migrations

修复迁移

If the database is in an inconsistent state, a repair migration brings it back to a consistent state. It is created by reading the live schema and diffing it against a target migration version, so the database must be reachable.

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

With a running

serverpod start

and MCP server

运行

serverpod start

并连接 MCP 服务器时

Create the repair migration using the
```
create_repair_migration
```
tool. Optional arguments:
```
version
```
(target migration version, defaults to the latest),
```
tag
```
, and
```
force
```
(required for destructive changes, or when no drift is detected).
Apply it using the
```
apply_migrations
```
tool, which applies both pending and repair migrations without restarting the server.

ALWAYS use the MCP server if it is available.

使用
```
create_repair_migration
```
工具创建修复迁移。可选参数：
```
version
```
（目标迁移版本，默认为最新版本）、
```
tag
```
和
```
force
```
（破坏性变更或未检测到差异时需要）。
使用
```
apply_migrations
```
工具应用修复迁移，该工具无需重启服务器即可应用待处理的迁移和修复迁移。

如果 MCP 服务器可用，请务必使用它。

ONLY if MCP server fails to connect

仅当 MCP 服务器连接失败时

bash

undefined

bash

undefined

Use the

--mode

flag to specify the run mode

使用

--mode

标志指定运行模式

Use the

--version

flag to specify the target version

使用

--version

标志指定目标版本

Use the

--force

flag to create a migration with destructive changes

使用

--force

标志创建包含破坏性变更的迁移

Use the

--tag

flag to name the migration

使用

--tag

标志为迁移命名

serverpod create-repair-migration [--mode production] [--version <name>] [--force] [--tag <tag>]


Apply the repair migration by restarting the server with `dart run bin/main.dart --apply-repair-migration`. Ask the user to run this command.

serverpod create-repair-migration [--mode production] [--version <name>] [--force] [--tag <tag>]


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

serverpod-migrations

Original

Translation

Serverpod Migrations

Serverpod Migrations

When migrations are needed

何时需要迁移

Standard flow

标准流程

With a running
`serverpod start`
and MCP server

运行
`serverpod start`
并连接 MCP 服务器时

ONLY if MCP server fails to connect

仅当 MCP 服务器连接失败时

Editing a generated migration

编辑生成的迁移

Repair migrations

修复迁移

With a running
`serverpod start`
and MCP server

运行
`serverpod start`
并连接 MCP 服务器时

ONLY if MCP server fails to connect

仅当 MCP 服务器连接失败时

Use the
`--mode`
flag to specify the run mode

使用
`--mode`
标志指定运行模式

Use the
`--version`
flag to specify the target version

使用
`--version`
标志指定目标版本

Use the
`--force`
flag to create a migration with destructive changes

使用
`--force`
标志创建包含破坏性变更的迁移

Use the
`--tag`
flag to name the migration

使用
`--tag`
标志为迁移命名