RisingWave 系统目录 Schema 迁移实战：基于 sea-orm-migration 的 Migrator CLI 使用与迁移文件编写指南

数据库流处理后端数据工程【免费下载链接】risingwaveEvent streaming platform for agentic AI. Continuously ingest, transform, and serve event streams in real time, at scale.项目地址https://gitcode.com/gh_mirrors/ri/risingwave点击查看免费下载RisingWave 的元数据Meta服务将系统目录System Catalog持久化在 SQL 数据库中默认为 SQLite也支持 PostgreSQL 与 MySQL所有编目对象表、物化视图、源、Sink、用户、Secret 等的结构都由src/meta/model/migration目录下的一套迁移文件Migration定义。本指南以该目录下的 README.md 为骨架结合仓库源码完整讲解 Migrator CLI 的九种操作命令、如何新增一个迁移文件、以及 MySQL 后端下大字段类型选择的特殊注意事项帮助开发者在涉及系统目录 Schema 变更时安全、正确地完成升级与回滚。背景为什么 RisingWave 需要迁移文件RisingWave 的 Meta 服务在启动时会通过 ORM 框架 SeaORM 管理数据库连接而系统目录的建表与表结构演进由 SeaORM Migration 机制负责。核心入口位于 lib.rs每个迁移文件都是一个独立的 Rust 模块例如m20230908_072257_init.rs初始建表、m20240617_070131_index_column_properties.rs为索引表添加列等Migrator::migrations()方法按严格顺序返回全部Boxdyn MigrationTrait实例列表这个顺序即迁移的应用顺序每个迁移文件实现MigrationTrait包含up升级与down回滚两个异步方法分别用于应用和撤销一次 Schema 变更。README 中特别给出了三条不可违背的铁律迁移文件只能应用一次每次应用都会被记录到系统表seaql_migrations中该表在 serde_seaql_migration.rs 中以versionapplied_at两列建模重复应用会被跳过新增 Schema 变更必须新建迁移文件而不是修改已发布的迁移文件绝对不要修改已经发布进入任何已发布版本的迁移文件除非你能确认该修改尚未包含在任何已发布版本中。在运行时Meta 服务启动时会调用Migrator::up自动应用所有待处理迁移相关调用点位于 controller/mod.rs如Migrator::up(this.conn, None)这意味着任何未应用的迁移文件都会在 Meta 服务启动时自动生效。Migrator CLI 的九种核心操作CLI 入口在 main.rs通过cli::run_cli(Migrator)启动。所有命令都必须在src/meta/model/migration目录下执行而非项目根目录并且需要设置DATABASE_URL环境变量指向目标数据库。1. 生成新迁移文件generateDATABASE_URLsqlite::memory: cargo run -- generate MIGRATION_NAME该命令需要一个数据库端点但实际上不会使用它故可用sqlite::memory:占位会在src/meta/model/migration/src/下生成一个形如m{时间戳}_{名称}.rs的新文件同时要求把mod声明与Box::new(...)实例按顺序补充进 lib.rsMIGRATION_NAME建议采用能概括变更内容的小写英文短语参考仓库现有命名如index_column_properties、add_rate_limit_to_source_catalog。2. 应用所有待处理迁移upcargo run不带任何子命令直接运行等价于应用所有尚未执行的迁移显式写法为cargo run -- up两种写法均会将DATABASE_URL指向的数据库升级到最新 Schema。在本地开发/测试场景若目标库是空的会依次执行从m20230908_072257_init开始的全量迁移链。3. 仅应用前 N 个待处理迁移cargo run -- up -n 10-n参数限制本次最多应用的迁移数量。上例表示只应用前 10 个尚未应用的迁移适合分步验证迁移脚本或调试部分迁移引起的兼容性问题。4. 回滚最近应用的迁移downcargo run -- down cargo run -- down -n 10不带-n时回滚最近一次已应用的迁移带-n 10时回滚最近 10 个已应用的迁移。回滚会调用迁移文件的down方法例如删除列、删除表。注意回滚与up相反按应用顺序的逆序执行。5. 重建数据库fresh / refresh / resetcargo run -- fresh删除数据库中所有表然后从头重新应用全部迁移。适合需要完全干净的 Schema 时使用。cargo run -- refresh先回滚所有已应用的迁移再重新应用全部迁移。与fresh的区别在于它通过down逐个撤销保留数据库本身再按顺序重放。cargo run -- reset仅回滚所有已应用的迁移不再重新应用最终数据库回到未迁移的空 Schema 状态。6. 检查迁移状态statuscargo run -- status列出每个迁移文件的状态Applied/Pending可用于核对seaql_migrations记录与磁盘上迁移文件是否一致是排查迁移未生效问题的第一步。各命令一览表命令作用是否破坏数据cargo run/cargo run -- up应用所有待处理迁移否仅新增cargo run -- up -n 10仅应用前 10 个待处理迁移否cargo run -- down回滚最近一次迁移是cargo run -- down -n 10回滚最近 10 次迁移是cargo run -- fresh删表后全量重建是全量cargo run -- refresh回滚后重新应用全部迁移是全量cargo run -- reset回滚所有迁移不重放是全量cargo run -- status查看全部迁移状态否如何新增一个迁移以 index_column_properties 为例README 推荐以 m20240617_070131_index_column_properties.rs 作为新增迁移的参考模板该文件展示了给已有表加一列的完整写法use sea_orm_migration::prelude::*; use crate::utils::ColumnDefExt; #[derive(DeriveMigrationName)] pub struct Migration; #[async_trait::async_trait] impl MigrationTrait for Migration { async fn up(self, manager: SchemaManager) - Result(), DbErr { manager .alter_table( Table::alter() .table(Index::Table) .add_column(ColumnDef::new(Index::IndexColumnProperties).rw_binary(manager)) .to_owned(), ) .await } async fn down(self, manager: SchemaManager) - Result(), DbErr { manager .alter_table( Table::alter() .table(Index::Table) .drop_column(Index::IndexColumnProperties) .to_owned(), ) .await } } #[derive(DeriveIden)] enum Index { Table, IndexColumnProperties, }该模板的要点#[derive(DeriveMigrationName)]自动以文件名作为迁移版本号保证迁移名全局唯一up通过SchemaManager对Index表执行alter_table add_column新增index_column_properties列列类型由rw_binary按后端自动选择down是对称的撤销操作执行drop_column表名与列名使用DeriveIden枚举定义避免手写字符串拼错。除模板外仓库中还可以参考两类典型迁移建表迁移见 m20230908_072257_init.rs其中通过assert_not_has_tables!宏断言目标表不存在后再逐张建表且在 MySQL 后端下先执行ALTER DATABASE CHARACTER SET utf8mb4 COLLATE utf8mb4_bin以保证大小写敏感的排序规则数据迁移可参考其他涉及字段类型/枚举变更的迁移文件。新迁移写完后务必同步在 lib.rs 中完成两处登记顶部添加mod m{时间戳}_{名称};在Migrator::migrations()的vec![...]中按时间顺序追加Box::new(m{时间戳}_{名称}::Migration)。一个典型的上线流程cd src/meta/model/migration # 1. 生成迁移骨架 DATABASE_URLsqlite::memory: cargo run -- generate my_schema_change # 2. 编辑生成的 .rs 文件实现 up/down并在 lib.rs 中登记 # 3. 本地用 SQLite 全量验证 DATABASE_URLsqlite::memory: cargo run # 4. 检查状态 DATABASE_URLsqlite::memory: cargo run -- status # 5. 验证回滚路径 DATABASE_URLsqlite::memory: cargo run -- down -n 1 DATABASE_URLsqlite::memory: cargo run -- up -n 1MySQL 后端的特殊注意事项大字段必须使用扩展构造器README 明确警告MySQL 的数据类型长度限制比 PostgreSQL / SQLite 严格得多。MySQL 中VARCHAR、TEXT、BLOB、BINARY等类型的最大长度为65,535 字节而 RisingWave 的系统目录中经常需要存储远超该上限的大字段例如SQL 定义视图、物化视图、函数定义体UDF 的函数体protobuf 编码的内部数据如列属性、表属性等序列化内容因此在迁移文件中禁止直接使用内置构造器ColumnDef::text或ColumnDef::blob而应使用仓库自定义的扩展。这些扩展实现在 utils.rs通过easy_ext宏为ColumnDef注入两个方法rw_binary适合存储二进制/序列化数据pub fn rw_binary(mut self, manager: SchemaManager) - mut Self { match manager.get_database_backend() { DatabaseBackend::MySql self.custom(extension::mysql::MySqlType::LongBlob), DatabaseBackend::Postgres | DatabaseBackend::Sqlite self.blob(), } }在MySQL上映射为LONGBLOB最大 4GB在PostgreSQL上映射为bytea在SQLite上映射为blob。适合用于包裹 protobuf 或其他序列化数据的二进制字段。上面index_column_properties示例中新增的列正是用它定义的。rw_long_text适合存储用户内容/长文本pub fn rw_long_text(mut self, manager: SchemaManager) - mut Self { match manager.get_database_backend() { DatabaseBackend::MySql self.custom(Alias::new(longtext)), DatabaseBackend::Postgres | DatabaseBackend::Sqlite self.text(), } }在MySQL上映射为LONGTEXT在PostgreSQL上映射为text在SQLite上映射为text。适合存储用户指定的内容如 UDF 函数体、SQL 定义等。选择建议存储内容推荐构造器原因SQL 定义、UDF 函数体等长文本rw_long_textMySQL 下映射为LONGTEXT突破 65,535 字节限制protobuf 序列化数据、二进制列属性rw_binaryMySQL 下映射为LONGBLOB突破 65,535 字节限制普通短字段常规构造器长度在限制范围内时无需特殊处理值得注意的是utils.rs中的方法签名都要求传入SchemaManager因为需要根据manager.get_database_backend()在运行时动态选择后端对应的列类型——这也保证了同一份迁移代码可以无差别运行于 SQLite、PostgreSQL 与 MySQL 三种后端之上。源码级补充迁移与系统表的配合迁移记录表seaql_migrationsSeaORM 迁移框架使用系统表记录已应用的迁移。RisingWave 在 serde_seaql_migration.rs 中复刻了该表模型version主键 applied_at时间戳并额外派生了serde序列化支持。该模型仅供元数据备份/恢复backup/restore使用其设计说明也特别指出迁移表名应通过MigratorTrait::migration_table_name覆盖默认为seaql_migrations。Meta 服务启动时自动迁移开发者在本地通过risedev或 Docker 启动 RisingWave 时Meta 服务会在初始化数据库连接后自动执行Migrator::up应用全部待处理迁移见 controller/mod.rs因此手动运行 CLI 主要面向新增迁移后的本地验证、CI 中的 Schema 一致性校验、以及备份恢复等运维场景。辅助宏lib.rs 还导出了两个实用宏供迁移文件内部使用assert_not_has_tables!断言若干表尚不存在用于建表迁移前的安全检查初始迁移即用它防止重复初始化drop_tables!以IF EXISTS ... CASCADE方式批量删除若干表常用于数据清理类迁移。小结RisingWave 的系统目录 Schema 演进完全依托 SeaORM Migration 机制迁移文件以时间戳 名称唯一标识up/down方法对称定义升级与回滚seaql_migrations系统表保证每个迁移只应用一次。日常开发中掌握generate、up、down -n、status等命令即可完成绝大多数 Schema 变更涉及 MySQL 部署时务必使用 utils.rs 提供的rw_long_text/rw_binary扩展来定义大字段避免触碰 65,535 字节的长度上限。修改已发布迁移文件是高风险操作新增变更请始终走生成新迁移 → 登记 lib.rs → 本地全量验证 → 应用的流程。赞分享数据库流处理后端数据工程【免费下载链接】risingwaveEvent streaming platform for agentic AI. Continuously ingest, transform, and serve event streams in real time, at scale.项目地址https://gitcode.com/gh_mirrors/ri/risingwave点击查看免费下载相关推荐SeaORM 数据库迁移与实体生成 CLI 完全指南sea-orm-cli 与 sea-orm-migration 实战SeaORM 数据库迁移与实体生成 CLI 完全指南sea orm cli 与 sea orm migration 实战 导读 SeaORM 项目为 Rust后端数据库ORMSeaORM Migrator CLI 迁移命令实战指南基于 salvo_example 的数据库迁移管理SeaORM Migrator CLI 迁移命令实战指南基于 salvo_example 的数据库迁移管理 本篇技术指南以 SeaORM 官方示例项目 sal后端数据库ORMFreeCAD CAM 输出生成深度解析G-code 后处理器的能力现状与扩展指南FreeCAD CAM 输出生成深度解析G code 后处理器的能力现状与扩展指南 FreeCAD 的 CAM 工作台负责把建模阶段产生的刀具路径翻译成机床可桌面应用3D建模图形学工业制造上一篇MACS3输出文件全解析narrowPeak与broadPeak结果的实战应用下一篇从线程混乱到精准控制rr框架中ThreadGroup与Task的协同设计创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考