Pdman 这个工具说实话在国产开源建模工具里算是一股清流。我最早接触它是因为要给一个老项目补数据库文档试了好几个工具都不顺手要么是英文界面看着费劲要么是生成文档还要收费直到同事甩给我这个绿色小工具才发现原来做数据库建模和逆向出文档能省下这么多事。如果你是刚听说 Pdman我用一句话给你定位这是一个免费、开源、跨平台的数据库建模工具支持中文界面并且内置了从建模到生成建表 SQL、再到一键输出数据库设计文档的完整闭环。它特别适合这几类人需要频繁给甲方或领导交数据库设计文档的开发人员负责老系统维护、手上只有线上库没有文档的运维或后端以及还在用 Visio 之类通用绘图工具画 ER 图的学生和初学者。1. 工具选型解析为什么在众多建模工具里选 Pdman先聊点实际的。数据库建模这件事市面上能选的工具其实不少各有各的优缺点。我挑几个大家常用的做个对比你就明白 Pdman 的位置在哪里了。ERWin 和 PowerDesigner是老牌商业软件功能确实强大。PowerDesigner 当年我在外企工作时用过它对企业级架构、数据仓库建模的支持非常成熟。但问题也很明显授权费不便宜界面还是上个世纪的风格学习曲线陡峭而且它是 Windows 平台的工具Mac 上想用就得开虚拟机。说实话如果你只是要建一个业务系统的库表结构用这类工具属于杀鸡用牛刀大部分功能你根本用不到还得忍受它那繁琐的操作逻辑。Navicat 和 DBeaver这类数据库客户端更多是把重点放在数据管理、查询、导入导出上。它们虽然也提供简单的 ER 图展示和模型功能但建模能力相对薄弱。你很难在 Navicat 里精细化地设计索引、约束、触发器这些对象它的模型视图更多是一个可视化浏览的功能而不是设计工具。Sybase PowerDesigner 的替代品里还有一个不能不提的是 MySQL Workbench。它自带建模功能如果你用的是 MySQL确实能直接上手画 ER 图和做正向逆向工程。但它是官方为 MySQL 量身定做的对其他数据库的支持就很一般而且界面同样偏老派一些操作逻辑也比较反人类。Pdman 的定位恰好填补了这些工具的空白。它最初是个人开源项目目标就很纯粹把数据库建模和文档生成这两件事做好并且对国内开发者友好。我用下来的感受是这么几点中文界面和中文文档生成这对国内团队太关键了。给甲方交付的《数据库设计说明书》能直接生成中文 Word 或 Markdown不用自己二次翻译。跨平台免费团队里有人用 Windows有人用 macOS大家都能跑同一个工具不需要额外付费也不涉及版权风险。操作思路清晰它的设计理念非常准确地切中了一个痛点数据库模型的核心就是“表、字段、关系、索引、字典”把这些要素管理好自然能产出高质量的建表脚本和设计文档。没有一堆用不上的企业级功能堆在界面上上手成本极低。导出 SQL 支持多种数据库方言同一套模型可以导出 MySQL、Oracle、PostgreSQL 等不同版本的建表语句。这个功能在做数据库迁移或支持多数据库版本的产品时特别实用。2. 核心功能拆解与实操步骤从安装到完成一次完整的数据库建模接下来进入正题我把一次完整的建模流程拆开按实际操作顺序讲透。为了演示方便我用一个常见的“用户-角色-权限”模型作为案例这套模型虽然简单但足够覆盖 Pdman 核心功能的使用场景。2.1 安装与初始化准备Pdman 的安装非常简单你现在去它的 GitHub 仓库或者搜索官方下载地址就能拿到对应操作系统的安装包。它是基于 Java 技术栈开发的所以理论上只要有 JRE 环境就能跑。如果你用的是 Windows下载 zip 包解压后找到启动脚本通常是startup.bat或者直接运行 exe 文件就能打开。macOS 用户下载 dmg 安装包拖进应用程序目录即可。Linux 用户可能需要给启动脚本添加执行权限这在国产工具里算是对开发者比较友好的了。第一次启动后你会看到 Pdman 的主界面左边是模型导航树中间是设计画布右边是属性面板。初次使用建议先看一下导航栏把界面布局混个眼熟。我不建议你一上来就百度各种“技巧”先把这个界面上的几个核心区域认清楚操作逻辑就通了一半。提示Pdman 的操作界面是纯中文的所以在学习和使用上它比 PowerDesigner 这种纯英文工具不知道友好到哪里去了。第一次打开界面你大概率能靠着直觉就完成基础操作。2.2 创建项目与数据源配置建模的第一步是定义连接Pdman 的模型文件是以.pdman格式保存到本地的 JSON 文件这意味着它天然适合放进 Git 仓库做版本管理。我见过不少团队用 Pdman 建模直接把模型文件当代码一样提交同事拉下来就能继续编辑这个体验是那些存在数据库里或私有格式里的商业建模工具给不了的。创建项目时Pdman 会引导你配置默认的数据源连接信息。这一步的核心是选择你最终要部署的目标数据库类型比如 MySQL、Oracle、PostgreSQL、SQL Server、SQLite、MariaDB 等。以我们的“用户-角色-权限”模型为例假设目标数据库是 MySQL 5.7 以上版本数据源配置里设置好数据库名、用户名、密码即可。这个配置的作用有两层在正向工程中Pdman 会根据你选的数据库类型生成对应方言的建表脚本。在反向工程中Pdman 需要连接真实的数据库来读取表结构信息。如果你不确定自己的数据库版本怎么办我的建议是保持默认配置先往下走后面导出 SQL 时再根据实际情况微调。Pdman 的 MySQL 模板兼容性做得不错5.7 和 8.0 的主要差异集中在字符集默认值上后面在导出步骤里可以改。2.3 设计逻辑模型从零创建表、字段、索引和关系数据源配置完成后就进入了核心的模型设计环节。我先建立三张核心表sys_user用户表存储系统用户的基础信息sys_role角色表存储角色定义sys_user_role用户角色关联表用于多对多关系右键左侧导航树中的“表”节点选择“新建表”然后在右侧属性面板设置表名、表注释、字段列表。第一步设置表基本信息表名使用小写加下划线的蛇形命名法这是国内开发者的主流习惯。表注释建议写清楚表的业务含义比如“用户信息表”而不是简单的“用户”这样以后生成的文档可读性会好很多。第二步定义字段sys_user表的字段设计如下字段名类型长度允许空默认值说明idBIGINT20否无主键IDusernameVARCHAR50否无用户名passwordVARCHAR200否无密码密文real_nameVARCHAR50是无真实姓名emailVARCHAR100是无邮箱phoneVARCHAR20是无手机号statusTINYINT4是1状态1启用0禁用create_timeDATETIME无是CURRENT_TIMESTAMP创建时间update_timeDATETIME无是CURRENT_TIMESTAMP更新时间在 Pdman 中新建字段时重点注意几个细节主键设置在字段上勾选“主键”选项生成 SQL 时会自动处理 PRIMARY KEY。自增MySQL 的 AUTO_INCREMENT 在 Pdman 中通过字段属性里的“自增”勾选实现。如果你用的是 Oracle这个选项会被自动忽略Oracle 序列需要另外处理。默认值CURRENT_TIMESTAMP这种表达式可以直接填在默认值输入框里Pdman 不会做额外转义会原样写进 DDL。第三步创建索引切换到“索引”页签点击“新增索引”。索引类型支持普通索引、唯一索引、全文索引。对于sys_user表我给username建立唯一索引给email和phone建立普通索引然后给组合查询场景建立一个(status, create_time)的联合索引。这里有一个我踩过的坑Pdman 的索引列表中每个字段点击上移/下移就能调整顺序这个顺序直接决定了索引的字段顺序。刚开始用的时候我没注意把联合索引字段顺序排反了导致 SQL 里索引一直没被命中排查了半天才发现是建模阶段字段顺序错了。第四步建立表关系切换到“关系”视图在画布上把sys_user_role.user_id拖到sys_user.id上Pdman 会自动识别且创建外键关系。同理把sys_user_role.role_id拖到sys_role.id上。Pdman 的关系建模支持一对一、一对多、多对多三种。我在设计时通常遵循一个原则逻辑模型保留外键关系但生成物理模型时会根据实际情况决定是否用物理外键。很多互联网团队为了分库分表方便会刻意避免物理外键只用逻辑外键。Pdman 在这个点上处理得比较灵活你可以选择生成关系或在生成 SQL 时去掉外键约束。2.4 使用字典与枚举规范字段取值的利器Pdman 的“字典”功能是一个容易被忽略但其实非常实用的模块。它对应数据库设计中的“枚举值管理”但比 SQL 里的 ENUM 类型要灵活得多。以sys_user.status字段为例它只有 1启用和 0禁用两种取值。我可以在字典管理中创建一个叫做“用户状态”的字典定义两个枚举项然后在字段属性里把status关联到这个字典。这样做的好处是什么生成的数据库设计文档里status字段会自动带上取值范围说明领导看文档时一眼就知道这个字段是干什么的。后续代码生成时这个字典可以映射为 Java 枚举类或前端常量定义减少团队内部的沟通成本。如果以后状态取值需要扩展比如加一个“已注销”状态只需维护字典定义不需要去改每一条 SQL 注释。同样的方法我可以再建“逻辑删除标志”“性别”“是否”等常用字典。这个习惯一旦养成你会发现数据库模型的“自描述性”强了很多不用去看代码就能理解字段含义。2.5 正向工程从模型导出建表 SQL模型设计完成后最激动人心的时刻就是生成 SQL。点击菜单栏的“正向工程”Pdman 会弹出一个预览窗口里面就是完整的目标库建表语句。这里多提一句Pdman 的正向工程生成 SQL 的规则是“智能”的不是每个数据库都一样。MySQL 模板会默认给 InnoDB 引擎和 utf8mb4 字符集PostgreSQL 模板则会生成SERIAL类型或IDENTITYOracle 模板则会按 Oracle 的语法生成。所以你前期选对了目标数据库这一步的产出基本上是开箱即用的。但是我要特别提醒一个我经常见到的坑Pdman 的默认 MySQL 模板中BIGINT类型的主键不会默认带UNSIGNED如果你的业务主键准备用雪花算法生成还是建议在字段设置里勾选无符号避免主键上限不够用。别觉得这是小事我见过不止一个项目上线后主键溢出的场景那个排查过程相当痛苦。导出的 SQL 可以直接复制到 Navicat 里执行也可以保存成.sql文件经过版本管理后统一执行。Pdman 支持导出增量 SQL也就是只生成新增或变更部分的语句这个功能对线上环境变更非常友好。2.6 反向工程从已有数据库逆向生成模型和文档如果说正向工程是“从设计到实现”那反向工程就是“从实现反推设计”。这个功能在维护老系统、接手离职同事的项目时简直是救命稻草。点击“反向工程”填入数据库连接信息Pdman 会读取数据库中的所有表、字段、索引、外键自动在画布上生成对应的模型关系图。整个过程比手动建表快了不止一个量级。我实际用下来的体验是表多的情况下超过100张表Pdman 会生成一个比较密集的关系图这时不要指望画布能自动排布得美观它只会按默认布局平铺。你可以手动调整每张表的位置。逆向生成的模型字段注释、索引、默认值都能比较准确地还原但触发器和存储过程是不会被带进模型的。这需要你自己在文档里补充说明。逆向之后建议赶紧执行一次“导出文档”把当前真实库表的现状沉淀成文档存档。万一以后库表被人改了你还有一份基线可对比。3. 文档生成与团队协作流的完整实践3.1 一键生成数据库设计文档Word/Markdown/HTMLPdman 作为一个自带文档生成能力的工具它让我最省心的地方就在这里。以前我给别人做数据库设计说明都是先截图再打开 Word 一点点排版三个小时的重复劳动想死的心都有。现在只需要点一下“生成文档”选择你想要的格式一份结构完好的《数据库设计说明书》就出来了。我比较推荐先出 Markdown 再转 Word的工作流原因有两点Markdown 生成速度快而且格式干净适合在 Git 里做版本管理。Word 版用于交付给非技术人员或者需要盖章的正式场合。Pdman 支持直接导出 Word也可以先用 Markdown 产出再通过 Pandoc 转成 Word 自己微调封面和页眉。生成出来的文档内容通常包含这几块数据表清单、每张表的字段明细含类型、长度、是否可空、默认值、注释、索引信息、表之间的关系描述。这些内容虽然看起来是“套话”但在评审会上你会发现有一个结构齐全的文档对方根本问不出太多刁钻问题因为该有的信息你都在文档里展示了。3.2 模型文件版本管理与多人协作建议前面提过Pdman 的模型文件本质上是 JSON 格式。这个特性看起来不起眼实际配合 Git 用起来能带来极大的协作优势。我建议团队做这样几件事在代码仓库里专门建一个docs/database目录把.pdman模型文件提交进去。约定一个规矩任何人修改表结构必须先在 Pdman 里改模型再导出 SQL不允许绕过模型直接进数据库改表。每次发布新版本在 Git 的提交说明里写好“更新了哪些表、哪些字段”。这样做一段时间以后你的版本库会自动形成一条清晰的数据库演进日志。新同事入职看这套历史记录比看任何上古文档都直观。多人同时编辑同一个.pdman文件时可能会遇到合并冲突。Pdman 的 JSON 结构还算友好冲突通常发生在同一个表的不同字段Git 会提示冲突你手动选择保留哪一份即可。如果团队模型文件比较大我建议拆分成“订单域”、“用户域”、“支付域”等多个模型文件不同模块由不同的负责人维护从根上降低冲突概率。3.3 用代码生成能力打通开发链路Pdman 还有一个被很多人忽略的能力基于模型生成代码。它会根据表结构和字段定义自动生成对应的 Java 实体类、Mapper 接口、MyBatis XML 映射文件等。虽然它的生成模板不像专门的低代码平台那么花哨但对于单体应用或中小团队来说生成的代码质量完全可用能省掉不少重复的 CRUD 代码编写时间。更重要的是因为代码是从模型生成的代码和数据库设计天然保持一致不可能出现实体类和表字段对不上的情况。我用它的方式一般先把模型维护到位然后生成一次代码作为“脚手架”具体的业务逻辑再在脚手架基础上去改。这样既享受了自动化带来的效率又不会因为模板的局限性而束缚业务实现。4. 常见问题与排查技巧实录4.1 连接数据库失败提示无法创建连接这恐怕是用到反向工程时最多发的故障我总结了一下90% 的情况出在下面几个原因未开放远程访问权限MySQL 或 PostgreSQL 默认只监听 localhost你需要检查目标库的 bind-address 配置。时区问题给 MySQL 连接地址加上?serverTimezoneAsia/Shanghai参数能解决大部分连接后查询时报时区错的问题。端口被防火墙挡住这个问题在云服务器上特别常见。你本地 Navicat 能连上但 Pdman 连不上多半就是网络策略问题检查目标主机的安全组规则。驱动缺失旧版本 Pdman 可能不内置所有数据库驱动如果你用的是比较新的数据库版本比如 PostgreSQL 15建议升级 Pdman 到最新版本或者手动把对应的 JDBC 驱动 jar 包放到安装目录的 lib 下。我的排查顺序是先在本机用命令行工具测一遍账号密码确认能连再看 Pdman 的连接参数是否和命令行一致最后才考虑网络和驱动的问题。4.2 生成的 SQL 执行失败数据类型和特殊字符的坑有一次我帮朋友生成一套 Oracle 的脚本执行时报“无效的关系运算符”最后定位到是字段名和 Oracle 关键字冲突了。Pdman 本身不会智能到自动帮你加引号所以这种坑非常隐蔽。建议每次生成 SQL 后至少在目标数据库上跑一遍验证脚本。尤其是字段名是否为desc、level、comment这类数据库保留字默认值是否和目标库语法兼容比如CURRENT_TIMESTAMP在 SQL Server 中可能不适用字段长度是否超出目标库的限制比如 MySQL 5.6 之前索引最长 767 字节utf8mb4 字段的 varchar 长度不能超过 191这类问题只有真实执行一次 SQL 你才能发现。Pdman 只是生成工具不替你把关所有数据库方言细节。4.3 生成文档时中文乱码或字体异常这个问题多见于 Windows 环境。解决思路很朴实在导出文档前检查你的系统有没有安装中文字体以及 Pdman 的配置文件里默认编码是否为 UTF-8。一般改成 UTF-8 之后重启工具问题就消失了。如果你用的是文档模板进行导出还需要检查模板自身的字体配置把标题和正文的字体调整为系统中文字体否则 Word 里可能会显示成“方框”。4.4 BigDecimal 与 decimal 映射不准确这是做 Java 项目的同事容易遇到的问题。Pdman 的 MySQL 逆向工程中decimal(10,2)类型会被映射成BigDecimal还是Double取决于你选的代码生成模板。市面上有些模板默认把所有小数都映射成 Double这会导致精度丢失。如果项目里对金额、折扣等字段有精度敏感要求记得在生成代码前检查模板中 decimal 的映射规则必要时改成BigDecimal。4.5 模型文件损坏或打不开怎么办.pdman文件本质是 JSON如果真的遇到文件损坏可以拿一个文本编辑器比如 VS Code直接打开看 JSON 结构哪里断了人工修一下再重新导入。当然这个操作比较硬核前提是你对 JSON 结构有点了解。更保险的方案是养成习惯每隔一段时间导出一次文档或 SQL 备份万一模型文件真坏了还能靠 SQL 反向工程把结构追回来。从我跟数据打交道这十年的经验来说Pdman 的定位非常清晰它不追求做成一个无所不能的企业级建模平台而是在“数据库建模”这个具体问题上把建模、SQL 生成、文档输出、代码生成这四件事做到了“小而美”。很多团队其实不需要 PowerDesigner 那种庞然大物他们需要的只是一个能让数据库设计和交付文档这件事省心的工具而 Pdman 恰好就是这个工具。如果让我给刚接触它的人一个建议我会说找一个小项目按照我上面的流程完整走一遍从建模到生成 SQL再到生成文档整个过程不需要半天时间。等你亲手把一条链路跑通了自然就明白在哪个环节能加自己的规范、在哪个环节可以自定义模板、在哪个环节需要特别小心。工具始终是工具能把它用出多大价值最终还是取决于你把设计规范沉淀到什么程度。最后分享一个我自己的使用习惯每次数据库版本的发布我不仅会保存当时的.pdman模型文件还会导出一份当时的数据库设计文档和一份完整建表 SQL三个文件一起打成一个版本标签。这样做的好处是任何时候想复盘当时的表结构设计都不需要重新连接数据库或者回忆直接解压那个标签所有东西都在里面了。这就是工具之外、习惯带来的长期复利。