重构迁移命名:id 纯时间戳,类名 MigrationId<时间戳>,文件名 <id>.cj,删除旧格式兼容

This commit is contained in:
2026-08-25 13:40:34 +08:00
parent 7947a4c8f4
commit 74eb8b576e
7 changed files with 95 additions and 102 deletions
+8 -7
View File
@@ -93,9 +93,9 @@ main() {
```cangjie
import simcu::orm.migrations.*
// 定义迁移(migrationId 用 "yyyyMMddHHmmss_名称",按字典序应用)
public class InitialCreate <: Migration {
public init() { super("20250701000000_InitialCreate", "创建用户表") }
// 定义迁移(migrationId 按字典序应用;CLI 生成 "yyyyMMddHHmmss" 时间戳格式,类名 MigrationId<时间戳>)
public class MigrationId20250701000000 <: Migration {
public init() { super("20250701000000", "创建用户表") }
public override func up(builder: MigrationBuilder): Unit {
builder.createTable("users") { tb =>
tb.column("id", ColumnTypes.BigIntCol).primary().autoInc().notNull()
@@ -137,7 +137,7 @@ main() {
let models = ArrayList<EntityModel>()
models.add(ModelCache.get<User>())
models.add(ModelCache.get<Product>())
let m0 = gen.initial("20250701000000_InitialCreate", "初始建表", models)
let m0 = gen.initial("20250701000000", "初始建表", models)
Migrator(datasource).migrate([m0])
// 2. 模型变更后:旧模型快照(上次的 models) vs 新模型 → 增量迁移(表/列增删改)
@@ -209,8 +209,8 @@ main(args: Array<String>) {
| 命令 | 作用 |
|------|------|
| `cjpm run -- orm add <迁移名>` | 从模型生成迁移 .cj 文件 + 更新注册文件 + 写入快照;模型无变化则跳过 |
| `cjpm run -- orm rm <迁移名或id>` | 移除已生成的迁移(删除迁移文件 + 注册条目;注册表清空时重置快照) |
| `cjpm run -- orm add [描述]` | 从模型生成迁移 .cj 文件 + 更新注册文件 + 写入快照(描述可空,仅写入注释与历史记录);模型无变化则跳过 |
| `cjpm run -- orm rm <迁移id或类名>` | 移除已生成的迁移(删除迁移文件 + 注册条目;注册表清空时重置快照) |
| `cjpm run -- orm update` | 连接数据库,按 `migrationId` 字典序应用所有未执行的迁移 |
| `cjpm run -- orm downgrade [目标]` | 回退迁移:无目标=回退最近一个;有目标=回退到该迁移之后(含该迁移的 down) |
| `cjpm run -- orm list` | 列出已注册迁移(需真实连接读取历史表) |
@@ -225,6 +225,7 @@ main(args: Array<String>) {
- **首次使用(无迁移)**:不需要建 `src/migrations/` 目录,也不要写 `import <应用包名>.migrations.*`(该子包不存在会导致编译失败);首次 `add` 时 CLI 自动创建目录并生成迁移文件 + 注册文件;
- **生成后手动加 import**:执行 `add` 生成首个迁移后,在 `main()` 所在文件手动加一行 `import <应用包名>.migrations.*`(如 `import myapp.migrations.*`)——注册文件在子包内惰性加载,只有 import 触发后 `update/downgrade/list` 才能看到迁移;之后新增迁移无需再动这行;
- 迁移 / 注册文件生成在 `src/migrations/`,该目录是**子包**,文件头 `package <应用包名>.migrations`(如应用包 `myapp` → `package myapp.migrations`);
- 迁移文件命名为 **id 的蛇形形式**(如 `20250701000000.cj`),仅含 migrationId,不包含描述;CLI 生成的 migrationId 为 `yyyyMMddHHmmss` 时间戳,**迁移类名自动为 `MigrationId<时间戳>`**(如 `MigrationId20250701000000`);迁移描述可空,写入文件头部 `// 描述: ...` 注释与迁移类 `super("...", "...")` 中;
- `add` 只生成不执行;执行迁移用 `update`(回退用 `downgrade`),或在应用启动时直接 `db.migrate()`;
- 快照持久化在 `src/migrations/snapshot.json`;`add` 用「旧快照 vs 当前模型」做 diff,所以**改模型后重新编译应用再 `add`** 即生成增量迁移;
- 生成源码文本已包含 `import std.collection.*` 等标准库引用,应用无需额外配置。
@@ -408,7 +409,7 @@ qb.page(2, 10) // PagedResult<User>(items/total/
### 5. 迁移
- `Migration` 基类:`super("20250701000000_InitialCreate", "描述")`,实现 `up` / `down`;
- `Migration` 基类:`super("20250701000000", "描述")`,实现 `up` / `down`;
- `MigrationBuilder`:`createTable` / `dropTable` / `addColumn` / `dropColumn` / `alterColumn` / `renameColumn` / `createIndex` / `dropIndex` / `rawSql`;
- `ColumnDefinition` 链式:`.primary()` `.autoInc()` `.notNull()` `.withUnique()` `.withMaxLength(n)` `.withDefault(value)`;
- `ColumnTypes`(定义于 `simcu::orm.sql`):`BigIntCol`(openGauss 自增 → BIGSERIAL)/ `IntCol`(自增 → SERIAL)/ `SmallIntCol` / `TinyIntCol` / `TextCol`(VARCHAR,默认 255)/ `BoolCol` / `FloatCol`(DOUBLE PRECISION)/ `RealCol` / `DateTimeCol` / `DecimalCol`(DECIMAL(18,6))/ `BinaryCol`(BYTEA);实际 DDL 映射由方言 `columnTypeSql` 决定;