ARTICLE DETAIL

资讯详情

深耕网站建设与运营推广的一线实战洞察。

使用 SeaORM CLI 从 Sakila 数据库一键生成 Mermaid ER 图(--er-diagram 实战与源码解析)

使用 SeaORM CLI 从 Sakila 数据库一键生成 Mermaid ER 图(--er-diagram 实战与源码解析) 后端数据库ORM【免费下载链接】sea-orm A powerful relational ORM for Rust项目地址https://gitcode.com/gh_mirrors/se/sea-orm点击查看免费下载本文导读本文围绕 SeaORM 仓库中 sea-orm-sync/tests/common/sakila/NOTES.md 记录的 ER 图再生命令展开完整拆解sea-orm-cli generate entity --er-diagram的每个参数、执行流程与源码实现并解读命令产物 entities.mermaid 的 Mermaid 语法语义。读完你将掌握如何对任意 PostgreSQL / MySQL / SQLite 数据库生成结构化的 Mermaid ER 图、如何控制实体文件的输出格式、以及 ER 图中 PK / FK / UK 与表间关系标记的生成规则。一、文档背景一条命令维护一份 ER 图在 SeaORM 仓库中sea-orm-sync的测试夹具使用经典 Sakila 数据库作为 PostgreSQL 测试数据。其目录下同时存放了两份文件NOTES.md全文只有一条命令说明如何重新生成测试目录下的实体与 ER 图entities.mermaid命令的产物一份 145 行的 MermaiderDiagram描述了 Sakila 全部 15 张表actor、address、category、city、country、customer、film、film_actor、film_category、inventory、language、payment、rental、staff、store的字段、主外键与多对多关系。NOTES.md 的定位非常清晰它不是讲解文档而是可复现的维护指令。当测试库结构演进后维护者只需在项目根目录执行这条命令即可让实体代码与 ER 图与数据库 schema 保持同步。原文如下DATABASE_URLpostgres://sea:sealocalhost/sakila cargo run --manifest-path sea-orm-cli/Cargo.toml -- generate entity -o tests/common/sakila --entity-format dense --er-diagram二、命令逐段拆解每个参数在做什么下面按从左到右的顺序逐段解析这条命令参数定义见 sea-orm-cli/src/cli.rs。1.DATABASE_URLpostgres://sea:sealocalhost/sakila环境变量注入数据库连接串格式为protocol://username:passwordhost/database_name。在 generate.rs 中数据库名通过database_name_from_url从 URL 路径的第一个段解析若 URL 中缺失数据库名例如postgresql://root:rootlocalhost:3306命令会直接 panic 提示 There is no database name as part of the url path对应源码中的单测test_generate_entity_no_database_section。注意DATABASE_URL也可以改用-u/--database-url参数传入两者等价。SeaORM CLI 支持三种数据库 scheme分别对应不同的 schema 发现实现见 generate.rsscheme说明备注postgres/postgresqlPostgreSQL可选-s/--database-schema默认public通过SET search_path指定 schemamysqlMySQL忽略--database-schemasqliteSQLite忽略--database-schema连接串形如sqlite://path/to.db编译时需启用对应的sqlx-postgres/sqlx-mysql/sqlx-sqlitefeature见 sea-orm-cli/Cargo.toml未启用相应 feature 时源码会直接panic!(mysql feature is off)。2.cargo run --manifest-path sea-orm-cli/Cargo.toml --以仓库根目录为起点直接运行sea-orm-cli包而无需预先cargo install。--manifest-path指定了 CLI 的清单文件--之后是传给程序本身的参数。这也意味着任何安装了该 CLI 的环境都可以用等价的sea-orm-cli generate entity ...形式执行cargo run只是仓库内开发调试的便捷写法。3.generate entitygenerate是 CLI 的顶层子命令之一另一个是migrate见 cli.rsentity是其下的代码生成子命令。执行流程由run_generate_command驱动generate.rs解析数据库 URL建立连接池sqlx_connect支持--max-connections与--acquire-timeout使用sea_schema的SchemaDiscovery对目标库做 schema 发现得到表、列、索引、约束的元数据依次经过三个过滤器--tables只生成指定表、--include-hidden-tables包含下划线开头的隐藏表、--ignore-tables跳过指定表默认跳过seaql_migrations对每种数据库做特殊清洗跳过生成列generated column见 issue #3094、剔除 PostgreSQL 的部分唯一索引等由EntityTransformer转换出实体结构随后生成代码文件与可选的ER 图最后调用rustfmt统一格式化。4.-o tests/common/sakila-o/--output-dir指定输出目录默认值为./见 cli.rs。命令执行时会先fs::create_dir_all确保目录存在。生成的文件包括每张表一个实体文件、mod.rs或加--lib时用lib.rs、prelude.rs、sea_orm_active_enums.rs以及本次主题的entities.mermaid。5.--entity-format dense控制实体文件的排版格式。源码中格式的解析逻辑generate.rs优先级为--expanded-format--frontend-format--entity-format value 默认格式。可用的格式与仓库测试目录一一对应sea-orm-codegen/tests 下的compact、dense、expanded、frontend四组快照格式特点仓库对应测试目录compact单行结构最省空间sea-orm-codegen/tests/compactdense字段紧凑排列的常规风格本文命令所用sea-orm-codegen/tests/denseexpanded展开式、带完整列定义注释sea-orm-codegen/tests/expandedfrontend适合前端/无后端场景的轻量格式sea-orm-codegen/tests/frontend6.--er-diagram本次主题的核心开关这是生成 ER 图的开关定义在 cli.rs#[arg( long, default_value false, help Also generate a Mermaid ER diagram as entities.mermaid in the output directory )] er_diagram: bool,在 generate.rs 中其执行分支非常简单直接if er_diagram { let diagram entity_writer.generate_er_diagram(); let diagram_path dir.join(entities.mermaid); fs::write(diagram_path, diagram)?; println!(Writing {}, diagram_path.display()); }即在实体写入之前先调用EntityWriter::generate_er_diagram()生成 Mermaid 文本固定写入输出目录下的entities.mermaid。ER 图完全由 schema 发现结果派生无需手写任何一行 Mermaid。三、源码级原理ER 图是如何生成的generate_er_diagram的实现位于 sea-orm-codegen/src/entity/writer/mermaid.rs整个算法只有三个步骤。步骤一构造 PK / FK 集合let pk_sets: VecHashSetstr self .entities .iter() .map(|e| e.primary_keys.iter().map(|pk| pk.name.as_str()).collect()) .collect(); let fk_sets: VecHashSetstr self .entities .iter() .map(|e| { e.relations .iter() .filter(|r| matches!(r.rel_type, RelationType::BelongsTo)) .flat_map(|r| r.columns.iter().map(String::as_str)) .collect() }) .collect();主键直接取自实体的primary_keys外键则从所有BelongsTo关系中收集其连接列——也就是说FK 的判定完全基于关系建模而非数据库元数据中的外键约束这与 SeaORM 以实体关系驱动代码生成的思路一致。步骤二输出每个实体的字段块write_entity_blockmermaid.rs为每个表输出一个 Mermaid 实体块列名后的约束标记按以下规则计算组合标记既是 PK 又是 FKPK,FK如 Sakila 的film_actor.actor_id仅 PKPK非 PK、是 FK 且唯一FK,UK如rental.inventory_id仅 FKFK唯一非 FKUK如rental.rental_date普通列无标记字段类型则通过col_type_namemermaid.rs将sea_query::ColumnType映射为 Mermaid 友好的短名称例如Integer - int、String(_) - varchar、Text - text、Decimal(_) - decimal、Enum{..} - enum、Array(_) - array、Custom(_) - custom无法映射的走unknown兜底。步骤三输出表间关系行write_relationsmermaid.rs负责关系线BelongsTo输出}o--||标签为连接列名例如 Sakila 中的customer }o--|| address : address_idHasOne/HasMany被直接continue跳过——因为其反向BelongsTo关系已经表达了同一条连线避免重复联结表conjunct / 多对多输出}o--o{标签为[联结表名]例如actor }o--o{ film : [film_actor]。所有关系行经BTreeSet去重后按字典序输出保证两次生成的结果完全一致、便于 diff 审查。这一点有专门的测试保障test_er_diagram_deduplicates_m2mmermaid.rs断言多对多关系只出现一次test_generate_er_diagrammermaid.rs则用一组博客 schema 断言了完整输出包括自引用关系user }o--|| user : parent_id的呈现方式。四、解读产物Sakila 的 entities.mermaid以 entities.mermaid 中的片段为例直观感受输出结构film_actor的actor_id、film_id被标为PK,FK——它既是复合主键又是两张父表的引用列film中rating是enum、special_features是array、fulltext是自定义类型custom印证了类型映射的覆盖面actor }o--o{ film : [film_actor]表达了通过联结表film_actor建立的多对多关系而联结表自身又以两条}o--||的BelongsTo线挂在两端film }o--|| language : original_language_id展示了同一张表出现多条指向同一目标的关系时如何区分普通语言与原始语言。这份文件可以直接粘贴进支持 Mermaid 的编辑器/文档平台Typora、GitLab、GitHub、VSCode 的 Mermaid 插件等渲染成可视化 ER 图用于测试夹具文档、架构评审或新人导读。五、在仓库中的应用场景与扩展用法场景一测试夹具自文档化在 SeaORM 仓库中sea-orm-sync/tests/common/sakila 目录同时承载实体代码与 ER 图。每当 Sakila 测试库的 schema 调整只需重跑 NOTES.md 的命令entities.mermaid与实体文件同步更新让测试数据结构一图看懂。这也是 NOTES.md 只有一条命令却极具维护价值的原因。场景二对任意业务库快速出图把命令中的 URL 换成你自己的数据库即可# PostgreSQL默认 public schema DATABASE_URLpostgres://user:passlocalhost:5432/mydb \ cargo run --manifest-path sea-orm-cli/Cargo.toml -- generate entity \ -o ./er --entity-format dense --er-diagram # 只关注部分表 DATABASE_URLpostgres://user:passlocalhost:5432/mydb \ cargo run --manifest-path sea-orm-cli/Cargo.toml -- generate entity \ -t order,order_item --er-diagram -o ./er # SQLite 同样支持 DATABASE_URLsqlite://./app.db \ cargo run --manifest-path sea-orm-cli/Cargo.toml -- generate entity \ -o ./er --entity-format dense --er-diagram与生成命令的其他联动参数ER 图是基于 schema 发现结果绘制的因此generate entity的表过滤参数同样作用于 ER 图值得掌握的几个常用项完整定义见 cli.rs-t/--tables仅对指定表出图适合大库聚焦核心域--ignore-tables跳过指定表默认跳过seaql_migrations--include-hidden-tables默认跳过表名以下划线开头的表此开关可纳入-s/--database-schemaPostgreSQL 指定 schema默认public--max-connections/--acquire-timeout控制 schema 发现连接池默认 1 个连接、30 秒超时--with-serde、--date-time-crate chrono|time、--big-integer-type i64|i32、--model-extra-derives等这些只影响生成的 Rust 实体代码不影响entities.mermaid的内容。将 ER 图纳入文档工作流entities.mermaid是纯文本文件可以直接被include/粘贴进 Markdown 文档、生成到 CI 产物中也可以作为 schema 变更评审的 diff 依据——由于关系行与字段块都是字典序、确定性输出任何 schema 变动都会产生可读的文本 diff天然适合代码评审。六、小结一条命令sea-orm-cli generate entity --er-diagram可从任意 PostgreSQL / MySQL / SQLite 数据库同步生成实体代码与 Mermaid ER 图一处实现ER 图由EntityWriter::generate_er_diagramsea-orm-codegen/src/entity/writer/mermaid.rs确定性生成PK/FK/UK 标记、类型映射、多对多去重均有源码与单测佐证一份样板仓库内 NOTES.md entities.mermaid 组合展示了测试夹具 自文档化 ER 图的工程实践可直接迁移到你自己的项目。如需进一步探索可从 sea-orm-cli/src/commands/generate.rs 的run_generate_command入口开始沿SchemaDiscovery - EntityTransformer - EntityWriter的调用链阅读完整实现。赞分享后端数据库ORM【免费下载链接】sea-orm A powerful relational ORM for Rust项目地址https://gitcode.com/gh_mirrors/se/sea-orm点击查看免费下载相关推荐使用 SeaORM CLI 从数据库生成实体代码与 Mermaid ER 图以 Sakila 示例库为例使用 SeaORM CLI 从数据库生成实体代码与 Mermaid ER 图以 Sakila 示例库为例 导读 本文围绕 SeaORM 仓库中 tests/c后端数据库ORMMetabase 模型Models排障完全指南创建失败、编辑失效与性能优化实战Metabase 模型Models排障完全指南创建失败、编辑失效与性能优化实战 模型是 Metabase 中一类特殊的已保存问题它将查询结果固化为可后端数据库ORM用 liam-hq/cli 从数据库 Schema 一键生成可视化 ER 图命令详解、源码剖析与 CI/CD 集成实战用 liam hq/cli 从数据库 Schema 一键生成可视化 ER 图命令详解、源码剖析与 CI/CD 集成实战 本文以 frontend/packa数据可视化数据库前端CLI上一篇MyComputerManager优雅解决Windows顽固快捷方式的管理利器下一篇OpenCV 添加中文完整方案基于 PIL 与 simsun 字体解决 putText 中文乱码faceai 项目实战创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表