generating-typeorm-migration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Generating TypeORM Migrations

生成TypeORM迁移

This skill covers the end-to-end process for creating a TypeORM database migration. It ensures migrations are generated correctly, named clearly, and never run automatically. Follow these steps in order every time.

本技能涵盖创建TypeORM数据库迁移的端到端流程，确保迁移生成正确、命名清晰且绝不会自动运行。请每次按以下顺序执行步骤。

Step 1 — Update the Entity

步骤1 — 更新Entity

Modify the relevant TypeORM entity file (located in

apps/api/src/core/<domain>/entities/

libs/

). Add or change columns, indexes, relations, etc. using TypeORM decorators.

Use generated migrations by default. Do not write migration SQL by hand unless TypeORM cannot represent the database object you need.

修改相关的TypeORM entity文件（位于

apps/api/src/core/<domain>/entities/

或

libs/

目录下）。使用TypeORM装饰器添加或修改列、索引、关联等。

默认使用生成的迁移。除非TypeORM无法表示你需要的数据库对象，否则不要手动编写迁移SQL。

Step 2 — Generate the Migration

步骤2 — 生成迁移

Run the following command from the project root, passing a

--name

flag with a clear descriptive slug:

bash

npm run migration:api:generate --name=<migration-name>

The name becomes part of the filename:

apps/api/src/database/migrations/<timestamp>-<migration-name>.ts

. Choose it carefully upfront — use kebab-case and follow the conventions from existing migrations:

```
add-
```
— adding a column, index, constraint, or trigger
```
remove-
```
/
```
delete-
```
/
```
drop-
```
— removing something
```
create-
```
— creating a new table
```
update-
```
/
```
rename-
```
/
```
replace-
```
/
```
normalize-
```
— modifying existing data or structure
```
migrate-
```
— moving/transforming data between columns or tables
```
new-
```
— introducing a new enum value or entity

Examples from this project:

bash

npm run migration:api:generate --name=add-new-office-index
npm run migration:api:generate --name=create-integration-table
npm run migration:api:generate --name=migrate-office-and-remcat-sources-to-integration-source
npm run migration:api:generate --name=add-has-active-office-to-place-trigger
npm run migration:api:generate --name=new-integration-mapper-enum

从项目根目录运行以下命令，传入

--name

标志并指定清晰描述性的短名称：

bash

npm run migration:api:generate --name=<migration-name>

该名称会成为文件名的一部分：

apps/api/src/database/migrations/<timestamp>-<migration-name>.ts

。请提前谨慎选择名称——使用短横线分隔命名法（kebab-case）并遵循现有迁移的命名规范：

```
add-
```
— 添加列、索引、约束或触发器
```
remove-
```
/
```
delete-
```
/
```
drop-
```
— 删除某项内容
```
create-
```
— 创建新表
```
update-
```
/
```
rename-
```
/
```
replace-
```
/
```
normalize-
```
— 修改现有数据或结构
```
migrate-
```
— 在列或表之间移动/转换数据
```
new-
```
— 引入新的枚举值或entity

项目中的示例：

bash

npm run migration:api:generate --name=add-new-office-index
npm run migration:api:generate --name=create-integration-table
npm run migration:api:generate --name=migrate-office-and-remcat-sources-to-integration-source
npm run migration:api:generate --name=add-has-active-office-to-place-trigger
npm run migration:api:generate --name=new-integration-mapper-enum

Step 2A — Handle TypeORM Limitations

步骤2A — 处理TypeORM限制

If the required database change cannot be expressed in TypeORM entity metadata, do not force it into the entity with a fake column or workaround just to make migration generation pass.

Typical examples:

Expression indexes, such as
```
USING GIST (ST_Transform(geom, 2056))
```
Custom SQL functions or triggers
Postgres features not supported by this TypeORM version's decorators/metadata model

In these cases:

Confirm that TypeORM really cannot model the change in this project version.
Keep the entity as the real source of truth for the actual columns and relations only.
Add a short code comment near the relevant entity field or in the entity-level DB notes that explains:
- what custom DB object exists
- which migration created it
- why it is not declared through TypeORM metadata
Create the migration intentionally for that custom SQL:

bash

npm run migration:api:create --name=<migration-name>

Fill in the migration file manually with the minimal
```
up()
```
/
```
down()
```
SQL required.

If you need a concrete project example for a custom migration plus matching entity comment, read

references/custom-migration-example.md

如果所需的数据库变更无法通过TypeORM entity元数据表达，不要为了让迁移生成通过而强行用假列或变通方法修改entity。

典型示例：

表达式索引，例如
```
USING GIST (ST_Transform(geom, 2056))
```
自定义SQL函数或触发器
当前TypeORM版本的装饰器/元数据模型不支持的Postgres特性

在这些情况下：

确认当前项目版本的TypeORM确实无法建模该变更。
仅将entity作为实际列和关联的真实数据源。
在相关entity字段附近或entity级别的数据库注释中添加简短代码注释，说明：
- 存在哪些自定义数据库对象
- 哪个迁移创建了它
- 为什么不通过TypeORM元数据声明
专门为该自定义SQL创建迁移：

bash

npm run migration:api:create --name=<migration-name>

在迁移文件中手动填写所需的最小
```
up()
```
/
```
down()
```
SQL语句。

如果需要自定义迁移加对应entity注释的具体项目示例，请阅读

references/custom-migration-example.md

。

Step 3 — Review the Generated File

步骤3 — 审查生成的文件

Open the newly created file and verify:

The
```
up()
```
method contains only the expected changes.
The
```
down()
```
method correctly reverts them.
No unrelated tables or columns are touched.

If the diff looks wrong, check whether other entities have unsaved changes that were picked up unintentionally.

For hand-written custom migrations, review the same way:

The SQL does only the intended custom change
The rollback is correct
The entity contains the explanatory comment when the DB object is not representable in TypeORM

打开新创建的文件并验证：

```
up()
```
方法仅包含预期的变更。
```
down()
```
方法能正确回滚这些变更。
未触及无关的表或列。

如果差异看起来有误，请检查是否有其他entity存在未保存的变更被意外捕获。

对于手动编写的自定义迁移，也要按相同方式审查：

SQL仅执行预期的自定义变更
回滚操作正确
当数据库对象无法在TypeORM中表示时，entity包含解释性注释

Step 4 — Stop Here. Do NOT Run the Migration.

步骤4 — 到此为止，请勿运行迁移

Never run
npm run migration:api:run
automatically. The developer runs migrations manually at the right time (e.g., before a deployment or after coordinating with the team).

Do not suggest running the migration. Do not run it "just to test". Simply leave the generated file in place and inform the user that the migration is ready and they should run it when appropriate.

绝不要自动运行
npm run migration:api:run
。开发者应在合适的时机手动运行迁移（例如部署前或与团队协调后）。

不要建议运行迁移，也不要“只是为了测试”而运行。只需保留生成的文件，并告知用户迁移已准备就绪，应在适当的时候运行。

Quick Reference

快速参考

Command	Purpose
`npm run migration:api:generate --name=<name>`	Generate a migration from entity changes
`npm run migration:api:create --name=<name>`	Create an empty migration file for custom/manual SQL
`npm run migration:api:show`	List applied/pending migrations
`npm run migration:api:run`	Run manually only — never automated
`npm run migration:api:revert`	Revert the last migration

命令	用途
`npm run migration:api:generate --name=<name>`	根据entity变更生成迁移
`npm run migration:api:create --name=<name>`	创建空迁移文件用于自定义/手动SQL
`npm run migration:api:show`	列出已应用/待处理的迁移
`npm run migration:api:run`	仅手动运行——绝不要自动化
`npm run migration:api:revert`	回滚上一次迁移

Key Paths

关键路径

Entities:

apps/api/src/core/<domain>/entities/

libs/domains/

Migrations:
```
apps/api/src/database/migrations/
```
TypeORM config:
```
apps/api/src/config/typeorm.config.ts
```

Entities:

apps/api/src/core/<domain>/entities/

或

libs/domains/

Migrations:
```
apps/api/src/database/migrations/
```
TypeORM配置:
```
apps/api/src/config/typeorm.config.ts
```