GenarrativeAI/Genarrative

Fork 0

Files

Codex 7cea26cf66

CI / verify (push) Has been cancelled

Details

docs: add spacetimedb schema change constraints

2026-04-29 15:31:53 +08:00

9.5 KiB

Raw Blame History

SpacetimeDB 表结构变更约束

本文档总结 SpacetimeDB 开发过程中修改表结构时需要遵守的约束，以及发生迁移冲突后如何在保留旧数据的前提下手动迁移。

背景

当对已有数据库重新执行 spacetime publish 时，SpacetimeDB 会尝试根据旧 module schema 和新 module schema 生成自动迁移计划。当前实现的重点是自动 schema migration，不是通用的脚本式数据迁移框架。

与 PostgreSQL 迁移模型的差别

PostgreSQL 的常见迁移模型是脚本驱动的 DDL migration。开发者显式写出每一步迁移动作，例如：

ALTER TABLE users DROP COLUMN old_name;
CREATE INDEX CONCURRENTLY idx_users_email ON users(email);
DROP TABLE old_table;

也就是说，PG 里能做什么主要取决于 PostgreSQL DDL 能力、锁风险、现有数据是否满足约束，以及 migration 工具如何组织执行。

SpacetimeDB 的迁移模型不同。schema 来自模块代码里的 #[table]、reducers 和类型定义。开发者修改模块代码后执行：

spacetime publish <DATABASE_NAME>

host 会比较新模块声明的 schema 和旧数据库 schema，然后尝试自动迁移。自动迁移能力是有限的：SpacetimeDB 更像是“模块代码声明世界，publish 时数据库尝试跟上，但只走安全路径”。

对常见变更，可以按下面方式理解：

变更	PostgreSQL	SpacetimeDB
加表	`CREATE TABLE` migration	自动允许
删表	`DROP TABLE`，生产需谨慎	高风险。当前代码只有限支持删除空表；非空表会失败
加字段	`ALTER TABLE ADD COLUMN`，可带默认值	只允许加在表定义末尾，并且必须有 default，例如 Rust `#[default(...)]`
删字段	`ALTER TABLE DROP COLUMN`	自动迁移禁止
改字段类型、重命名、调顺序	可用 DDL 或拆成多步 migration	自动迁移通常禁止
加普通索引	`CREATE INDEX` / `CREATE INDEX CONCURRENTLY`	自动允许
删索引	`DROP INDEX`	允许，但可能破坏某些 subscription query
加唯一约束或主键	可先清理数据再加	对已有表自动迁移禁止
删除唯一约束	可做	自动允许移除 `#[unique]`
删除主键注解	可做	允许，但可能破坏旧客户端缓存行为

一句话概括：PG 迁移更自由，但风险由开发者和 migration 流程管理；SpacetimeDB 迁移更保守，系统只自动接受它能证明相对安全、客户端不容易坏的 schema 演进。

总体原则

对已有表做变更时，应优先选择向后兼容的增量式变更。
不要直接删除、改名、重排或重定义已有列。
对复杂结构变更，应新增目标表，通过 reducer 或后台批处理把旧数据搬到新表。
等数据迁移完成、旧客户端完成升级、旧表数据清空后，再移除旧表。
开发环境可以使用 --delete-data 重建数据库，生产环境不要用它作为数据迁移方案。

通常安全的变更

这些变更一般可以自动迁移，并且通常不会破坏现有客户端：

新增表。
新增索引。
添加或移除 auto-increment/sequence 类注解，但新增 sequence 会有额外数据范围预检查。
将表从 private 改为 public。
新增 reducer。
移除 unique constraint。
新增 view，或在兼容范围内更新 view。

可能破坏客户端但可确认后发布的变更

这些变更可以生成自动迁移计划，但可能使旧客户端不兼容。CLI 会要求用户确认，并通过 BreakClients policy 携带 token 继续发布。

给已有表末尾新增带 default 的列，例如 Rust #[default(...)]。
删除空表。
删除或改变 view 的返回列、参数、上下文等不兼容部分。
将 public 表改为 private。
移除 primary key 注解。
移除索引，尤其是旧客户端订阅查询依赖该索引时。
RLS 规则增加、删除或变化。
删除或修改 reducer，使旧客户端继续调用旧 reducer 时失败。

会触发冲突或拒绝自动迁移的变更

以下变更通常会在自动迁移规划阶段失败，服务端返回 AutoMigrateError，CLI 表现为需要 manual migration：

删除已有列。
重命名已有列。
重排已有列。
在已有表中间新增列。
给已有表新增没有 default value 的列。
修改已有列类型，除非是布局兼容的受限变更。
修改 product/sum 类型时减少字段或 variant。
修改 product/sum 类型时重命名字段或 variant。
修改类型导致 layout size 或 alignment 不兼容。
给已有表新增 unique constraint。
修改已有 unique constraint。
修改 table type。
修改 event flag。
修改 index accessor name。

规划通过但执行时仍会失败的情况

有些变更可以生成迁移计划，但执行阶段仍可能失败：

删除非空表：当前代码会生成 RemoveTable，但执行时会检查 row count。只有空表可以删除，非空表会失败并回滚。
schedule 相关变更：规划层可能生成 AddSchedule 或 RemoveSchedule，但执行层目前仍返回 not implemented。
新增或修改 sequence 时，如果已有数据落在新 sequence 的分配范围内，预检查会失败。
新增索引、RLS、view 重算等操作如果底层校验或执行失败，也会导致本次更新回滚。

冲突后的系统行为

发生冲突时，SpacetimeDB 默认不会自动修改旧数据，也不会执行用户自定义迁移脚本。

常见结果：

发布前预检查发现冲突：CLI 打印原因并中止发布。
服务端迁移规划失败：API 返回 400 Database update rejected: ...。
迁移执行中失败：当前事务 rollback，旧数据库和旧 module 继续运行。
只有显式使用 --delete-data 或 --delete-data=on-conflict 时，才会清空旧数据并用新 module 重建数据库。

保留旧数据的手动迁移方式

生产环境推荐使用增量迁移，而不是直接修改旧表结构。

建议步骤：

保留旧表。

不要直接删除或修改旧表的关键字段。例如保留 character。
新增目标表。

新建 character_v2，结构定义为目标 schema。新增表属于自动迁移支持范围。
发布兼容中间版本。

中间版本同时包含旧表和新表，并添加迁移 helper/reducer：
- 读数据时，优先读新表。
- 新表没有对应行时，从旧表读取，转换后写入新表。
- 写数据时，优先写新表。
- 如果仍需兼容旧客户端，同步写旧表。
- 大量历史数据通过 migrate_batch(limit) 之类的 reducer 分批迁移。
验证迁移完成。

检查新表行数、主键覆盖、关键字段一致性和客户端升级情况。
清空旧表数据。

通过 reducer 分批删除旧表数据。因为当前实现只允许删除空表。
删除旧表定义。

旧表为空后，再从 schema 中移除旧表并发布最终版本。

增量迁移示例

下面示例展示从旧表 character 迁移到新表 character_v2 的基本模式：

fn get_character(ctx: &ReducerContext, player: Identity) -> CharacterV2 {
    if let Some(row) = ctx.db.character_v2().player_id().find(player) {
        return row;
    }

    let old = ctx
        .db
        .character()
        .player_id()
        .find(player)
        .expect("character not found");

    let migrated = CharacterV2 {
        player_id: old.player_id,
        nickname: old.nickname,
        level: old.level,
        class: old.class,
        alliance: Alliance::Neutral,
    };

    ctx.db.character_v2().insert(migrated.clone());
    migrated
}

批量迁移时，应限制每次处理的行数，避免单个事务过大：

#[spacetimedb::reducer]
fn migrate_character_batch(ctx: &ReducerContext, limit: u32) {
    let mut migrated = 0;

    for old in ctx.db.character().iter() {
        if migrated >= limit {
            break;
        }

        if ctx.db.character_v2().player_id().find(old.player_id).is_some() {
            continue;
        }

        ctx.db.character_v2().insert(CharacterV2 {
            player_id: old.player_id,
            nickname: old.nickname,
            level: old.level,
            class: old.class,
            alliance: Alliance::Neutral,
        });

        migrated += 1;
    }
}

发布前检查清单

发布涉及表结构变更的 module 前，至少检查：

是否删除、改名、重排或修改了已有列。
新增列是否位于表定义末尾，并且是否有 default value。
是否给已有表新增了 unique 或 primary key 约束。
是否删除了非空表。
是否修改了 event table、schedule table、RLS 或 view。
是否会破坏旧客户端订阅、reducer 调用或本地缓存假设。
是否需要先发布中间版本做增量迁移。
是否已在 staging 数据库用真实规模样本测试过发布。

结论

SpacetimeDB 的表结构变更策略应以“新增、兼容、分阶段”为核心。实际开发时应尽量只做 additive change：加表、加索引、在末尾加带默认值的字段。遇到自动迁移冲突时，不要直接清库或强行修改旧表；应保留旧数据，新增目标 schema，通过 reducer 分批迁移数据，逐步切换客户端，最后在旧数据清空后移除旧表。

9.5 KiB Raw Blame History Unescape Escape