SeaORM Poem 示例迁移指南：使用 Migrator CLI 管理数据库 Schema

后端数据库ORM【免费下载链接】sea-orm A powerful relational ORM for Rust项目地址https://gitcode.com/gh_mirrors/se/sea-orm点击查看免费下载本篇技术指南基于 sea-orm 仓库中的 examples/poem_example 示例项目完整讲解 SeaORM 迁移Migration子系统在真实 Web 应用中的落地方式如何通过 Migrator CLI 应用、回滚、重置与查询迁移状态并结合 Poem 示例的迁移模块源码 深入剖析up/down/fresh/refresh/reset/status六类命令的底层执行逻辑与调用链。读完本文你将掌握 SeaORM 迁移的 CLI 操作全流程并能看懂迁移代码的结构与程序内自动迁移的触发机制。关联文档与仓库定位本指南的核心文档是 examples/poem_example/migration/README.md它是一份浓缩的 Migrator CLI 操作速查表罗列了迁移生命周期中最常用的七个命令场景。该文档所在的migrationcrate 是 Poem Web 示例一个基于 Tera 模板的博客应用的数据库迁移模块与其平级的还有apiPoem 服务端、entity实体定义两个 crate共同组成一个完整工作区定义见 examples/poem_example/Cargo.toml。需要说明的是SeaORM 迁移 CLI 的行为由sea-orm-migrationcrate 统一提供因此本文讲解的命令与原理同样适用于仓库中其他示例如 axum_example/migration、rocket_example/migration 等下文将以 Poem 示例为具体载体展开。迁移模块的项目结构在动手运行命令之前先看清迁移模块的组成。Poem 示例的迁移 crate 包含 4 个关键文件examples/poem_example/migration/ ├── Cargo.toml # 依赖声明与 feature 配置 └── src/ ├── lib.rs # Migrator 聚合器注册全部迁移 ├── main.rs # CLI 入口调用 cli::run_cli ├── m20220120_000001_create_post_table.rs # 迁移 1创建 post 表 └── m20220120_000002_seed_posts.rs # 迁移 2写入种子数据其中 src/lib.rs 是整个迁移体系的枢纽它通过MigratorTrait实现Migrator结构体在migrations()方法中按顺序返回迁移列表pub struct Migrator; #[async_trait::async_trait] impl MigratorTrait for Migrator { fn migrations() - VecBoxdyn MigrationTrait { vec![ Box::new(m20220120_000001_create_post_table::Migration), Box::new(m20220120_000002_seed_posts::Migration), ] } }而 src/main.rs 则极为精简——全部 CLI 逻辑都委托给sea-orm-migration提供的cli::run_cliuse sea_orm_migration::prelude::*; #[tokio::main] async fn main() { cli::run_cli(migration::Migrator).await; }这意味着只要你的迁移 crate 实现了MigratorTrait并像上面这样编写入口就能直接获得一整套迁移命令行工具无需自己解析参数。环境准备数据库连接与依赖配置Migrator CLI 通过环境变量读取数据库连接信息。从 sea-orm-migration/src/cli.rs 的Cli结构体定义可以看出CLI 支持以下全局参数参数环境变量说明-u,--database-urlDATABASE_URL数据库连接 URL必填未设置时会报错Environment variable DATABASE_URL not set-s,--database-schemaDATABASE_SCHEMA数据库 schema 名PostgreSQL 下可选、默认publicMySQL 与 SQLite 下被忽略-v,--verbose—输出 debug 级别的日志在运行迁移命令前通常先在工作区根目录创建.env文件写入DATABASE_URL。CLI 启动时会通过dotenv().ok()自动加载.env见 cli.rs 的run_cli_with_connection函数。Poem 示例默认使用 SQLite因此典型的配置形如DATABASE_URLsqlite://posts.db?moderwc?moderwc表示读写并在不存在时自动创建数据库文件。若使用 PostgreSQL还需在DATABASE_SCHEMA中指定 schema默认public。依赖配置上migration/Cargo.toml 给出了两个关键点[dependencies.sea-orm-migration] features [ # Enable following runtime and db backend features if you want to run migration via CLI runtime-tokio-native-tls, sqlx-sqlite, ] path ../../../sea-orm-migration # remove this line in your own project version ~2.0.3 # sea-orm-migration version运行时与数据库后端 feature 必须匹配你的目标数据库注释明确提示若要经由 CLI 运行迁移需要启用对应的 runtime如runtime-tokio-native-tls与 db backend如sqlx-sqlite、sqlx-postgresfeaturepath指向的是本仓库内的 crate在独立项目中应删除这一行仅保留version此外还声明了对entity与tokio的依赖后者为 CLI 的异步运行时提供支持。Migrator CLI 命令速查完整继承原文档原 README 文档给出的全部命令如下每一条均可在迁移模块目录下直接运行应用全部待执行的迁移cargo runcargo run -- up应用前 10 个待执行的迁移cargo run -- up -n 10回滚最后应用的迁移cargo run -- down回滚最后 10 个已应用的迁移cargo run -- down -n 10删除数据库中的全部表然后重新应用所有迁移cargo run -- fresh回滚所有已应用的迁移然后重新应用所有迁移cargo run -- refresh回滚所有已应用的迁移cargo run -- reset检查所有迁移的状态cargo run -- status关于-n参数需要补充两点语义其一up -n 10中的-n意为 number of migrations to be applied即本次最多应用 10 个待执行迁移其二down -n 10表示回滚最近应用的 10 个迁移。从 cli.rs 的run_migrate_inner可以看到down分支会把num以Some(num)传入而up分支默认分支在无子命令时以None表示“应用全部”。命令底层的执行逻辑与调用链上述每个命令最终都落在MigratorTrait的方法上。对照 cli.rs 中run_migrate_inner的匹配逻辑match command { Some(MigrateSubcommands::Fresh) migrator.fresh(db).await?, Some(MigrateSubcommands::Refresh) migrator.refresh(db).await?, Some(MigrateSubcommands::Reset) migrator.reset(db).await?, Some(MigrateSubcommands::Status) migrator.status(db).await?, Some(MigrateSubcommands::Up { num }) migrator.up(db, num).await?, Some(MigrateSubcommands::Down { num }) migrator.down(db, Some(num)).await?, _ migrator.up(db, None).await?, }各命令的语义差异可以这样理解命令底层方法行为cargo run无参数/upMigratorTrait::up按注册顺序应用所有未执行的迁移每次迁移调用其up()方法up -n 10MigratorTrait::upnum10只应用前 10 个待执行迁移down/down -n 10MigratorTrait::down逆序回滚最近应用的迁移逐个调用迁移的down()方法freshMigratorTrait::fresh先删除库中全部表等价于重置到空库再应用全部迁移refreshMigratorTrait::refresh先回滚全部已应用迁移再重新应用全部迁移resetMigratorTrait::reset仅回滚全部已应用迁移不重新应用statusMigratorTrait::status列出每个迁移的待执行/已应用状态不修改数据库其中fresh、refresh、reset三者的差别值得重点记忆fresh走的是“删表”路线refresh走的是“回滚再应用”路线而reset只回滚不重建——日常开发中refresh是最常用的“重建数据库”方式因为它能同时执行迁移的down与up两个方向的代码可更完整地验证迁移的可逆性。此外CLI 还支持两个无需数据库连接的子命令见run_non_db_commandinit初始化迁移目录与generate生成新的迁移文件模板它们在 Poem 示例中未直接使用但在用sea-orm-cli从零搭建项目时非常有用。从源码看迁移如何被执行以 Poem 示例的第一个迁移 m20220120_000001_create_post_table.rs 为例它展示了迁移文件的标准骨架#[derive(DeriveMigrationName)] pub struct Migration; #[async_trait::async_trait] impl MigrationTrait for Migration { async fn up(self, manager: SchemaManager) - Result(), DbErr { manager .create_table( Table::create() .table(post) .if_not_exists() .col(pk_auto(id)) .col(string(title)) .col(string(text)) .to_owned(), ) .await } async fn down(self, manager: SchemaManager) - Result(), DbErr { manager .drop_table(Table::drop().table(post).to_owned()) .await } }要点拆解#[derive(DeriveMigrationName)]自动根据类型名Migration派生迁移名与文件前缀的m20220120_000001时间戳配合形成全局唯一、按时间排序的迁移标识up()使用sea_orm_migration::schema提供的辅助函数如pk_auto、string配合Table::create()构建建表语句if_not_exists()保证重复执行安全down()是对称的撤销操作调用drop_table删除post表。fresh/refresh/reset等命令能工作前提就是每个迁移都实现了可逆的down()。第二个迁移 m20220120_000002_seed_posts.rs 演示了如何在迁移中执行数据操作种子数据let db manager.get_connection(); let seed_data vec![ (First Post, This is the first post.), (Second Post, This is another post.), ]; for (title, text) in seed_data { let model post::ActiveModel { title: Set(title.to_string()), text: Set(text.to_string()), ..Default::default() }; model.insert(db).await?; }关键点在于迁移不仅能改表结构还能通过manager.get_connection()拿到数据库连接直接以ActiveModel的方式插入记录——这也是为什么种子数据、字典表初始化等任务可以自然地放进迁移脚本中。对应的down()则通过post::Entity::delete_many().filter(post::Column::Title.is_in(...))按标题精确清理种子数据保证回滚后数据状态与迁移前一致。程序内自动迁移不依赖 CLI 的另一种执行方式值得注意的一个细节是Poem 示例的 Web 服务在启动时就会自动执行迁移而无需手动运行 CLI。见 api/src/lib.rs 的启动流程// create post table if not exists let conn Database::connect(db_url).await.unwrap(); Migrator::up(conn, None).await.unwrap();这段代码在服务启动后直接调用Migrator::up将所有未应用的迁移应用一遍迁移表内部保证幂等已应用的会跳过。这是一种非常实用的生产部署模式把迁移与应用启动绑定省去额外运维步骤。它说明MigratorTrait的方法既可以被 CLI 包装调用也可以在你的业务代码里直接调用两条路径共用同一套迁移列表与幂等机制。因此在实际项目中你通常有两种选择开发阶段在迁移模块目录下使用本文速查表中的 CLI 命令up/down/fresh等随时调整 Schema部署阶段像 Poem 示例这样在应用启动时调用Migrator::up(conn, None)让迁移随服务一起完成。两者可以共存——CLI 管理的迁移状态表与程序内执行的迁移状态表是同一份不会互相冲突。小结本文以 examples/poem_example/migration/README.md 的命令速查表为骨架结合 Poem 示例的迁移源码完整覆盖了 SeaORM Migrator CLI 的七个核心命令场景并深入到了sea-orm-migration的 CLI 实现层从DATABASE_URL/DATABASE_SCHEMA的连接配置到up/down/fresh/refresh/reset/status与MigratorTrait方法的映射关系再到迁移文件up()/down()的编写范式与程序内自动迁移的用法。掌握这些内容后无论你是要在新项目中用 SeaORM 搭建 Schema 管理还是接手现有 sea-orm 工程都能准确、安全地执行每一次迁移操作。赞分享后端数据库ORM【免费下载链接】sea-orm A powerful relational ORM for Rust项目地址https://gitcode.com/gh_mirrors/se/sea-orm点击查看免费下载相关推荐Iosevka 27.0.1 新字符详解VERY MUCH LESS-THAN / GREATER-THANU22D8 / U22D9的源码实现与构建验证Iosevka 27.0.1 新字符详解VERY MUCH LESS THAN / GREATER THANU22D8 / U22D9的源码实现与构建后端数据库ORMSubstrate 依赖解析zeebo/xxh3 在 Go 中的 XXH3 非加密哈希算法与性能基准实战Substrate 依赖解析zeebo/xxh3 在 Go 中的 XXH3 非加密哈希算法与性能基准实战 本篇文章聚焦当前仓库 substrate 中作为间接人工智能AI AgentAgent 沙箱云原生容器运行时零信任SeaORM Migrator CLI 迁移命令完全指南生成、应用、回滚与状态管理实战SeaORM Migrator CLI 迁移命令完全指南生成、应用、回滚与状态管理实战 导读 本文以 examples/loco_example/migrat后端数据库ORM上一篇三步彻底卸载Windows系统Microsoft Edge浏览器的专业方案下一篇网盘直链下载终极解决方案一键获取九大网盘真实下载链接创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考