最有效的大库逆向工程路径是:先用 pg_dump -s 配合 -n 和 --exclude-table 精确导出结构,再用 sqlacodegen 生成模块化 SQLAlchemy 模型,最后用 erdiagram 基于模型快速产出可版本化的 SVG ER 图。
用 pg_dump + schema-only 提前过滤掉干扰数据
大型数据库逆向工程最常卡在「导出太慢」和「er图里塞满视图/函数/历史表」。直接跑全库 pg_dump 或用 gui 工具连生产库点几下,十有八九生成一堆无用节点,连线乱成蜘蛛网。
真正有效的起点是只取结构、且提前剔除非核心 schema:
-
pg_dump -s -n public -n tenant_123 --exclude-table='.*_audit' mydb > schema.sql—— 用-n锁定业务 schema,--exclude-table干掉审计日志类表 - 避免用
--include-table模糊匹配(如'user_*'),PostgreSQL 会扫描所有表名再过滤,大库下反而更慢 - 如果库中有大量
partitioned table,记得加--no-tablespaces,否则某些工具解析时会因表空间路径缺失报错ERROR: tablespace "pg_default" does not exist
用 sqlacodegen 生成 Python ORM 模型而非直连数据库
很多团队想用 MySQL Workbench 或 DBeaver 的 ER 建模功能,但大库一连就卡死,或者导出的 .mwb 文件动辄几百 MB,根本打不开。这时候该换思路:不画图,先落地可读、可版本化的模型定义。
sqlacodegen 把表结构转成清晰的 SQLAlchemy 类,天然支持模块化切分:
- 按业务域拆包:
models/user.py、models/order.py,每个文件只含相关表,ForeignKey引用用字符串(如"user.id")避免循环导入 - 加
--tables参数精确控制范围:sqlacodegen postgresql://... --tables users,orders,order_items > models/order.py - 注意默认生成的
__table_args__里可能含Comment,某些旧版 SQLAlchemy 会报TypeError: 'comment' is an invalid keyword argument,删掉或升级到 2.0+
用 erdiagram 基于 ORM 模型生成轻量级 SVG 图
有了分好模块的 Python 模型,就别再折腾数据库直连绘图工具了。用 erdiagram 这类基于代码的方案,速度快、可控性强、还能 git diff 对比结构变更。
它不解析 SQL,而是 import 你的 models.order 模块,自动提取 __tablename__ 和 ForeignKey:
- 安装后执行:
erdiagram --models models.order --output order.svg,5 秒内出图,文件大小通常 - 如果外键指向其他模块(比如
order.user_id → user.id),需用--models同时指定多个文件:--models models.order models.user - 默认不显示字段类型,加
--show-types可看Integer、String(32),但别对齐排版抱希望——它生成的是语义图,不是出版级图表
模块切分后如何维护跨域关系一致性
把模型按业务拆开后,最容易出问题的是「关系断裂」:比如 order.py 里定义了 user_id 外键,但 user.py 里没配反向关系,或两个模块用了不同命名约定(user_id vs owner_id)。
这不是工具能自动解决的,得靠机制约束:
- 所有外键字段名统一用
{ref_table}_id格式(如customer_id、product_id),禁止用owner_id、created_by这类语义模糊名 - 在 CI 中加检查脚本:用
ast解析所有models/*.py,验证每个ForeignKey字符串是否能在对应模块中找到__tablename__ - ER 图只是快照,真正要依赖的是
models/目录下的 Python 文件——它们可测试、可 review、可加 type hint,比任何图形都可靠
越大的库,越不能靠一张图管全局。模块边界一旦划清,就别再试图把所有表塞进同一张 SVG 里;留几个关键聚合根图(如「订单履约链」),其余交给代码和文档,反而更可持续。

















