SeaORM 迁移器 CLI 实战指南：从 generate 到 fresh/refresh/reset 的完整命令手册

后端数据库ORM【免费下载链接】sea-orm A powerful relational ORM for Rust项目地址https://gitcode.com/gh_mirrors/se/sea-orm点击查看免费下载导读本文围绕 SeaORM 迁移器Migrator的命令行界面展开以 react_admin 示例项目中实际使用的 migration/README.md 为骨架系统讲解迁移文件的生成、应用、回滚、重建与状态查询的全部 CLI 命令并结合 sea-orm-migration 与 sea-orm-cli 的源码实现说明每条命令背后的执行链路与适用场景。读完本文你将能独立在任意 SeaORM 项目中完成从创建迁移到上线运维的完整数据库版本管理流程。一、什么是 SeaORM 迁移器 CLI在 SeaORM 生态中sea-orm-migration是一个独立的 crate负责把数据库结构变更组织成一个个按时间排序的迁移migration文件并用一张名为seaql_migrations的表记录哪些迁移已经应用过、哪些尚未应用。迁移器的 CLI 入口位于 sea-orm-migration/src/cli.rs它基于clap解析命令行参数并在启动时通过dotenv().ok()读取.env文件中的环境变量。每个迁移项目都会有一个main.rs作为 CLI 入口react_admin 示例的 migration/src/main.rs 只有短短几行use sea_orm_migration::prelude::*; #[tokio::main] async fn main() { cli::run_cli(migration::Migrator).await; }也就是说所有命令都是通过cargo run把Migrator交给cli::run_cli来执行的。命令分发逻辑在 sea-orm-migration/src/cli.rs 的run_migrate_inner中fresh、refresh、reset、status、up、down分别对应MigratorTrait上的同名方法未指定子命令时默认执行up(None)即应用全部待执行迁移。二、环境与依赖准备在运行任何迁移命令之前需要满足两个前提。1. 数据库连接配置CLI 通过DATABASE_URL环境变量获取连接串通过可选的DATABASE_SCHEMA指定数据库 schema。在 sea-orm-migration/src/cli.rs 中Cli结构体将这两个参数声明为全局参数因此它们既可以作为命令行参数传入也可以直接设置环境变量export DATABASE_URLpostgres://loco:locolocalhost:5432/loco_react_admin_development cargo run -- status其中DATABASE_SCHEMA仅对 PostgreSQL 生效默认值为public对 MySQL 和 SQLite 该参数会被忽略。react_admin 示例在 backend/config/development.yaml 中通过{{ get_env(nameDATABASE_URL, ...) }}读取同一个环境变量保证应用与迁移器使用同一套数据库配置。2. 异步运行时特性要在 CLI 中连接数据库必须在sea-orm-migration依赖上启用至少一个ASYNC_RUNTIME特性和对应的数据库驱动特性。react_admin 的 migration/Cargo.toml 给出了最小配置[dependencies.sea-orm-migration] features [ runtime-tokio-rustls, ] version ~2.0.3这里启用了runtime-tokio-rustls作为异步运行时如果使用 MySQL 或 SQLite还需在sea-orm侧开启对应的驱动特性。三、生成新的迁移文件cargo run -- migrate generate MIGRATION_NAME这是文档列出的第一条命令用于生成一个新的空迁移文件。它内部调用 sea-orm-cli/src/commands/migrate.rs 的run_migrate_generate执行过程可以分为三步校验名称迁移名不能包含连字符-因为迁移文件最终会成为 Rust 模块名生成文件名使用%Y%m%d_%H%M%S格式的时间戳作为前缀默认取 UTC 时间生成形如m20240520_173001_files.rs的文件universal_time默认true可用--local-time改为本地时间注册迁移自动把新模块写入lib.rs的mod声明并追加到Migrator::migrations()返回的Vec中。迁移文件名的命名规范可以从 react_admin 的实际文件看出m20220101_000001_users.rs、m20231103_114510_notes.rs、m20240520_173001_files.rs —— 均为m 时间戳 语义化名称。每个迁移通过DeriveMigrationName派生宏自动从文件名提取迁移名。提示migrate generate与模板初始化migrate init一样属于不需要数据库连接的命令。在 sea-orm-migration/src/cli.rs 的run_non_db_command中这类命令会被提前拦截处理处理完成后直接返回不会建立数据库连接。四、应用迁移upcargo run cargo run -- up cargo run -- up -n 10前两条命令效果相同都是应用所有待执行的迁移第三条只应用前 10 个待执行迁移。-n对应Up子命令的num参数sea-orm-cli/src/cli.rs类型为Optionu32不传则全部应用。底层执行链为CLI 解析出Up子命令后调用MigratorTrait::up(db, steps)sea-orm-migration/src/migrator.rs其内部先执行install确保迁移记录表存在再通过get_pending_migrations拿到所有状态为Pending的迁移最后按声明顺序逐个执行MigrationTrait::up。核心状态流转可参考 migrator.rsMigrationStatus只有Pending未应用与Applied已应用两种状态。以 users 表迁移为例m20220101_000001_users.rsup方法用 schema 辅助函数声明表结构let table table_auto(users) .col(pk_auto(id)) .col(uuid(pid)) .col(string_uniq(email)) .col(string(password)) .col(string(api_key).unique_key()) .col(string(name)) .col(string_null(reset_token)) .col(timestamp_null(reset_sent_at)) .col(string_null(email_verification_token)) .col(timestamp_null(email_verification_sent_at)) .col(timestamp_null(email_verified_at)) .to_owned(); manager.create_table(table).await?;pk_auto、uuid、string_uniq、string_null、timestamp_null等都是 sea-orm-migration/src/schema.rs 提供的列类型辅助函数可据此推断这些函数分别对应自增主键、UUID、唯一字符串、可空字符串与可空时间戳等列定义。五、回滚迁移downcargo run -- down cargo run -- down -n 10down用于回滚最近应用的迁移默认只回滚 1 个Down子命令的num默认值为 1见 sea-orm-cli/src/cli.rs-n 10则回滚最近 10 个。回滚的执行路径与up对称MigratorTrait::down内部调用exec_downsea-orm-migration/src/migrator.rs它先通过get_applied_migrations取出所有Applied状态的迁移再按时间倒序执行每个迁移的down方法。迁移的down方法需要自行实现。react_admin 的三个迁移都提供了对应的回滚逻辑例如删除 notes 表m20231103_114510_notes.rsasync fn down(self, manager: SchemaManager) - Result(), DbErr { manager .drop_table(Table::drop().table(notes).to_owned()) .await }需要特别留意 sea-orm-migration/src/lib.rs 中MigrationTrait的定义down方法有默认实现默认行为是返回DbErr::Migration(We Dont Do That Here)即默认不允许回滚。因此凡是需要支持down的迁移都必须像示例中那样显式实现。此外MigrationTrait还提供use_transaction方法用于控制迁移是否在事务中执行返回None默认时遵循后端惯例PostgreSQL 使用事务MySQL/SQLite 不使用返回Some(true)强制开启Some(false)则关闭自动事务包裹。六、重建数据库fresh / refresh / reset这三条命令容易混淆文档明确区分了三者的语义命令行为危险性cargo run -- fresh删除数据库中所有表然后重新应用全部迁移最高数据全部丢失cargo run -- refresh回滚全部已应用迁移然后重新应用全部迁移高依赖down实现cargo run -- reset回滚全部已应用迁移并卸载迁移记录表高依赖down实现从源码看三者的实现差异非常清晰sea-orm-migration/src/migrator.rsfresh调用exec_fresh先install创建迁移记录表再drop_everything删除数据库中的所有表最后exec_up全量重建refresh先exec_down(None)回滚全部再exec_up(None)全量重放reset先exec_down(None)回滚全部再uninstall删除seaql_migrations迁移记录表本身但不删除其他业务表。需要强调的是refresh与reset能否成功回滚完全取决于每个迁移是否实现了down方法而fresh直接物理删除所有表即使迁移没有down实现也能执行。三条命令均会破坏数据仅适合在开发或测试环境中使用生产环境务必谨慎。七、查看迁移状态statuscargo run -- statusstatus用于检查所有迁移的当前状态。其实现sea-orm-migration/src/migrator.rs会先install迁移记录表再遍历get_migration_with_status的结果逐条输出每个迁移的名称与状态Pending或Applied。状态判定的依据来自两张对照表代码中的Migrator::migrations()声明了全部迁移文件数据库中的seaql_migrations表记录了已应用的历史。该表的结构定义在 sea-orm-migration/src/seaql_migrations.rs包含version迁移版本号即迁移文件名主键与applied_at应用时间戳两个字段。get_migration_with_status将代码声明的迁移与数据库记录做比对得出每个迁移是Pending还是Applied。八、命令速查表将文档中的全部命令整理为速查表方便日常查阅目标命令说明生成迁移cargo run -- migrate generate NAME生成空迁移文件并自动注册名称不能含-应用全部迁移cargo run等价于cargo run -- up应用全部迁移cargo run -- up应用所有待执行迁移应用前 N 个迁移cargo run -- up -n 10只应用前 10 个待执行迁移回滚最近 1 个迁移cargo run -- down默认回滚 1 个回滚最近 N 个迁移cargo run -- down -n 10回滚最近 10 个已应用迁移重建数据库cargo run -- fresh删所有表后全量重放回滚后重放cargo run -- refresh回滚全部后重新应用全部回滚全部cargo run -- reset回滚全部并卸载迁移记录表查看状态cargo run -- status输出每个迁移的 Pending/Applied 状态九、在 react_admin 示例中的实际应用react_admin 示例的迁移项目位于 examples/react_admin/backend/migration目前包含三个按时间顺序排列的迁移形成一条清晰的数据模型演进链m20220101_000001_users.rs —— 创建users表包含 UUID、唯一邮箱、密码、API Key 以及一系列可空的邮箱验证/密码重置时间戳字段m20231103_114510_notes.rs —— 创建notes表含可空的标题与内容字段m20240520_173001_files.rs —— 创建files表并通过ForeignKey::create()声明files.notes_id指向notes.id的外键约束。这三个迁移在 migration/src/lib.rs 中被显式注册fn migrations() - VecBoxdyn MigrationTrait { vec![ Box::new(m20220101_000001_users::Migration), Box::new(m20231103_114510_notes::Migration), Box::new(m20240520_173001_files::Migration), ] }MigratorTrait::migrations()的返回顺序即迁移的执行顺序因此新迁移必须追加到Vec末尾否则会导致应用顺序与时间戳顺序不一致。实际工作中建议始终通过migrate generate生成迁移让工具自动完成注册避免手工修改lib.rs出错。此外react_admin 后端基于 Loco 框架构建其 development.yaml 中开启了auto_migrate: true意味着应用启动时会自动执行迁移CLI 方式则适用于手动控制迁移时机的开发与运维场景两者可互补使用。十、小结SeaORM 迁移器 CLI 以极简的命令集覆盖了数据库结构管理的全部常规操作migrate generate负责创建并注册迁移up/down负责增量前进与回滚fresh/refresh/reset负责整库重建status负责审计当前状态。理解这些命令背后的执行链路——尤其是seaql_migrations记录表、MigratorTrait的状态比对逻辑以及down默认不可用的设计——是安全使用迁移器、避免开发环境数据事故的关键。无论你是在集成 SeaORM 的独立项目还是像 react_admin 这样基于 Loco 的应用中本文的命令速查表都能直接作为日常开发的参考。赞分享后端数据库ORM【免费下载链接】sea-orm A powerful relational ORM for Rust项目地址https://gitcode.com/gh_mirrors/se/sea-orm点击查看免费下载相关推荐Pillow 移植指南从 PIL 迁移到 Pillow 的完整实战手册Pillow 移植指南从 PIL 迁移到 Pillow 的完整实战手册 本指南基于仓库文档 docs/porting.rst https://link.git图像处理计算机视觉Fresh 从 twind 迁移到 Tailwind CSS 完整指南Fresh 从 twind 迁移到 Tailwind CSS 完整指南 自 Fresh 1.6 起Fresh 官方内置了正式的 Tailwind CSS 插件后端前端Terragrunt CLI 重设计迁移指南从 terragrunt- 前缀到全新命令体系的完整升级手册Terragrunt CLI 重设计迁移指南从 terragrunt 前缀到全新命令体系的完整升级手册 本文是围绕 RFC 3445 https://linkCLIDevOps云原生上一篇终极指南Octotree如何通过file-icons库打造直观的文件图标系统下一篇5分钟掌握microG GmsCore开源Google服务替代方案完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考