推荐用 pg_dump --schema-only 配合 schema_plus_core 生成可复现、可 diff、可 CI 触发的结构快照，替代 GUI 工具导出；再通过 dbdiagram.io 或 mermaid-cli 渲染为 PDF，并校验 NOT NULL、外键列名和中文字体，Git 中仅提交 schema.sql、er.mmd 和构建脚本。
用 pg_dump + schema_plus_core 生成结构快照，别依赖 GUI 工具导出
gui 工具（如 dbeaver、datagrip）点“导出 er 图”看似方便，实际导出的 pdf 常缺外键标注、字段类型缩写混乱、中文注释错位——本质是它们把可视化渲染逻辑和导出逻辑耦合了，一换主题或缩放就崩。团队共享需要的是可复现、可 diff、可 ci 触发的输出。
推荐路径：用命令行工具先提取结构元数据，再交由稳定绘图工具生成 PDF。PostgreSQL 用户优先用 pg_dump --schema-only 配合 schema_plus_core 插件生成标准 schema.rb 或 JSON；MySQL 可用 mysqldump --no-data + mysql-schema-diagram 转 SVG。
-
pg_dump -U user -h host db_name --schema-only --no-owner --no-privileges > schema.sql—— 去掉权限和 owner，避免协作时权限报错 - 加
--inserts会混入数据，导 ER 图时绝对不要加 - 如果表有
COMMENT ON COLUMN，确保连接用户有SELECT权限，否则注释丢失
用 dbdiagram.io 或 mermaid-cli 渲染，不手动画
人工拖拽画 ER 图无法版本化，改一个字段就得重传 PDF。真正能进 Git 的只有文本描述，再靠工具转图。dbdiagram.io 支持粘贴 SQL DDL 直接生成交互式图，导出 PDF 时选“High quality (vector)”；更可控的是用 Mermaid：mermaid-cli 可将 .mmd 文件批量转 PDF，且 erDiagram 语法天然支持外键方向、基数标注（||、}o）。
- 从
schema.sql提取建表语句后，用脚本自动转成erDiagram格式（注意：REFERENCES行要映射为--|>关系，不是所有转换脚本都处理这个） - Mermaid 渲染 PDF 依赖 Puppeteer，若报
Failed to launch chrome，加环境变量PUPPETEER_EXECUTABLE_PATH指向已安装 Chrome - dbdiagram.io 对
GENERATED ALWAYS AS或分区表支持弱，遇到解析失败就切回 SQL 手动删掉非核心 DDL 再粘贴
PDF 导出后必须校验三处，否则对接开发时当场翻车
导出完成不等于可用。PDF 是静态快照，但数据库在动——如果没校验关键信息是否对齐，下游开发按图建索引或写 JOIN 时会直接报错。
- 打开 PDF 后搜索
NOT NULL，确认所有业务强约束字段都有标注（GUI 工具常漏掉ALTER TABLE ... ALTER COLUMN ... SET NOT NULL的后续变更） - 比对 PDF 里的外键列名和实际
\d table_name输出，某些工具会把user_id显示成users.id，但 PDF 里只写了id，开发以为是本表字段 - 检查字体：若 PDF 中中文显示为方框，说明导出时未嵌入中文字体，
mermaid-cli需加参数--puppeteer-config '{"args":["--font-render-hinting=none"]}'并指定系统中文字体路径
Git 里存什么、不存什么，决定能否真正协同
PDF 本身不该进 Git 主分支，它只是产物。真正要 commit 的是生成它的原材料和指令——否则 A 导出一次、B 改个字段又导一次，PDF 文件 diff 完全不可读，版本也失去意义。
- 必须提交：
schema.sql（或schema.json）、er.mmd、make-pdf.sh（含mermaid-cli调用命令和字体配置） - 禁止提交：
er.pdf到 main 分支；可放在/docs/er/但需 gitignore 掉构建中间文件（如er.html） - CI 流水线里跑
make pdf后自动上传到内部文档站，链接写进 README —— 这样每次 merge 后 PDF 自动更新，链接永远有效
最麻烦的不是导出动作本身，是让所有人默认“PDF 是副产品，DDL 和 mermaid 源才是真相”。一旦有人绕过流程直接改 PDF，整个链路就断了。
