简介这是一款轻量级Java开发的数据库文档自动生成工具面向后端开发者、DBA及技术文档工程师解决PowerDesigner等重型建模工具部署复杂、学习成本高的痛点适用于日常数据库表结构沉淀、团队知识共享与项目交付文档快速输出。资源包共21个文件含10个核心Java源码实现多数据库驱动适配与模板渲染、3张功能示意图jpg、2个配置文件xml、1个Windows启动脚本bat与1个Linux启动脚本sh辅以README.md、pom.xml及HTML格式说明文档整体仅188KB开箱即用且便于二次定制。已有326人学习下载用户可直接运行编译后的程序按交互式提示选择PostgreSQL/MySQL/Oracle类型输入库名、主机、端口及账号密码即可一键生成结构清晰的Markdown与Word格式文档涵盖表名、字段、类型、注释及关系说明显著提升数据库文档维护效率。1. 这不是又一个“导出说明书”的玩具database-doc-generator 是能嵌进 CI 流水线的轻量级数据库文档自动化引擎你有没有在交付前最后一刻被产品追着要「最新版数据库字段说明」有没有因为某张表加了个is_deleted字段没同步到 Confluence导致测试环境查不到软删数据而翻车更糟的是用 PowerDesigner 或 ER/Studio 这类重型建模工具——画个图要装 2G 客户端、配 JDK 版本、改注册表、导出 Word 还得手动删页眉页脚……结果文档刚生成开发已经ALTER TABLE加了三列。database-doc-generator 就是为这种真实血泪场景生的它不碰 ER 图、不依赖 GUI、不维护元模型只认一件事——你数据库里SHOW CREATE TABLE出来的那一段 DDL 字符串。用 Java 写成的命令行工具5 分钟配置完java -jar docgen.jar --url jdbc:mysql://...一跑立刻吐出结构清晰、带注释解析、支持 Markdown 和 Word 双格式的文档。适合中小型团队做数据库契约管理、新人快速上手、CI 中自动校验 DDL 变更是否同步到文档库。它不替代 DBA 的深度建模但能让你告别「文档永远比代码慢半拍」的玄学困境。2. 为什么选它不是因为“轻”而是因为它把 DDL 当唯一真相源2.1 DDL 即契约拒绝元数据二义性从根源掐断文档漂移很多团队用注释如Table(name user, comment 用户主表)或实体类 Javadoc 生成文档问题在于Java 类可以改DDL 可能没同步DBA 直接 SQL 建表Java 类却忘了更新甚至不同环境 DDL 已分叉文档还指着旧类。database-doc-generator 的设计哲学非常硬核它完全不读 Java 实体类、不连 Hibernate SessionFactory、不解析 MyBatis XML 映射文件。它只做三件事通过 JDBC 连接数据库或读取本地 SQL 文件执行SHOW CREATE TABLE xxx或解析CREATE TABLE语句把COMMENT、DEFAULT、NOT NULL、KEY、ENGINE等原生 DDL 属性逐字映射为文档字段。这意味着只要你的生产库information_schema是可信的生成的文档就一定是当前真实状态。我曾在某模拟项目X 的灰度发布中用它每小时扫描一次核心库发现两个环境间user_profile表的updated_at字段默认值不一致一个是CURRENT_TIMESTAMP一个是NULL这个差异在人工 review DDL 脚本时被漏掉了——而 docgen 的 Markdown 输出里两行Default值并排写着一眼揪出。2.2 Java 实现的底层优势可控、可嵌入、可审计它用 Java 写不是为了“跨平台”这种空话而是三个实打实的好处JDBC 驱动全生态兼容MySQL 5.7/8.0、PostgreSQL 12、Oracle 19c、SQL Server 2019只要 JDBC URL 能通它就能连。不像某些 Python 工具对 Oracle cx_Oracle 版本极其敏感无运行时依赖污染打包成单 jar不依赖系统 Python 环境、不装 node-gyp 编译、不拉 npm 包。运维同学扔进 Docker 容器里java -version检查完就能跑日志与异常完全可控所有 SQL 执行、字段解析、模板渲染过程都走 SLF4JDEBUG 级别下能看到每一行 DDL 是怎么被切分成列名、类型、注释的。某次遇到 MySQL 8.0 的json类型解析失败打开 DEBUG 日志30 秒定位到TypeParser类里少处理了一个JSON枚举值——补上后重新编译问题消失。这种可调试性在 shell 脚本或 JS 工具里是奢侈品。2.3 Markdown Word 双输出不是噱头是交付链路的真实需求很多人觉得 “Word 输出” 是过时功能但现实很骨感向客户交付系统时合同要求提供.docx格式《数据库设计说明书》盖章归档内部审计需要 Word 文档插入页眉含密级标识、页脚含版本号和生成时间非技术人员如业务方更习惯双击打开 Word 查字段而不是在 VS Code 里看 Markdown。database-doc-generator 的 Word 输出不是简单 HTML 转 DOCX而是用 Apache POI 直接操作 OOXML 结构表格用XWPFTable生成标题用XWPFParagraph设置样式甚至支持自定义 Word 模板.docx文件里预设好公司 Logo 位置、字体、页边距。而 Markdown 输出则严格遵循 GitHub Flavored Markdown表格对齐、代码块语法高亮、链接跳转全部可用直接丢进 GitBook 或 Docsify 就能当在线文档站用。两者共享同一套解析引擎保证内容零偏差——这是很多“先转 Markdown 再用 pandoc 转 Word”的方案做不到的。3. 三步落地从下载到生成一份可交付的数据库文档3.1 下载与环境准备确认 JDK 版本拒绝“版本玄学”提示该工具最低要求 JDK 8u202推荐使用 JDK 11 LTS。JDK 17 也可用但需确认 JDBC 驱动兼容性如 MySQL 8.0 驱动需 8.0.33。第一步去 GitHub Release 页面下载最新版 jar 包截至本文撰写时最新为v2.3.1文件名形如database-doc-generator-2.3.1.jar。不要用git clone后自己mvn package——除非你明确要改源码否则官方 release 包已包含所有依赖Shaded Jar开箱即用。第二步确认 Java 环境java -version # 正确输出应类似 # openjdk version 11.0.22 2024-01-16 # OpenJDK Runtime Environment (build 11.0.227-post-Ubuntu-0ubuntu2~22.04.1) # OpenJDK 64-Bit Server VM (build 11.0.227-post-Ubuntu-0ubuntu2~22.04.1, mixed mode, sharing)若提示command not found请先安装 OpenJDK 11Ubuntu/Debiansudo apt update sudo apt install openjdk-11-jdk -y第三步准备数据库连接凭证。强烈建议不要在命令行明文写密码改用配置文件方式更安全、可纳入 Git 忽略# 创建 config.yaml路径随意比如 ./conf/db-config.yaml cat ./conf/db-config.yaml EOF jdbc: url: jdbc:mysql://192.168.5.100:3306/myapp_db?useSSLfalseserverTimezoneAsia/Shanghai username: doc_reader password: your_secure_password driver-class-name: com.mysql.cj.jdbc.Driver output: format: [markdown, word] markdown: output-dir: ./docs/markdown word: template-path: ./templates/company-template.docx # 若无此文件用默认模板 output-dir: ./docs/word tables: include: [user, order, product] # 只生成指定表留空则全库 exclude: [audit_log_%] # 支持通配符排除 EOF注意doc_reader账号只需SELECT权限查information_schema.TABLES/COLUMNS绝不给SUPER或FILE权限符合最小权限原则。3.2 命令行执行支持三种输入模式按需选择工具支持三种数据源模式对应不同协作阶段▶ 模式一直连数据库开发/测试环境常用java -jar database-doc-generator-2.3.1.jar \ --config ./conf/db-config.yaml \ --verbose--verbose参数会打印详细日志连接成功、查询了哪些系统表、解析了多少张表、生成了几个文件。首次运行建议必加便于排查连接问题。▶ 模式二解析本地 SQL 文件CI/CD 流水线首选当数据库无法直连如生产库隔离或需确保文档与发布包 DDL 严格一致时让 DBA 提供schema-ddl-20240501.sql文件java -jar database-doc-generator-2.3.1.jar \ --sql-file ./ddl/schema-ddl-20240501.sql \ --output-format markdown,word \ --output-dir ./docs/generated/此时工具会跳过 JDBC 连接直接用正则 ANTLR 解析 SQL 文件中的CREATE TABLE语句。它能正确处理多语句、反引号包裹的表名、跨行定义——这点比手写 sed/awk 脚本可靠得多。▶ 模式三指定单表 DDL 字符串紧急救火用当某张表结构突变需立刻生成说明发给前端又来不及改配置时echo CREATE TABLE user (id BIGINT PRIMARY KEY COMMENT 用户ID, name VARCHAR(50) NOT NULL COMMENT 用户名) ENGINEInnoDB; | \ java -jar database-doc-generator-2.3.1.jar \ --stdin-dll \ --output-format markdown \ --output-dir ./tmp/--stdin-dll参数告诉工具从标准输入读 DDL适合管道操作。生成的user.md会包含字段表、索引说明、建表语句原文5 秒搞定。3.3 输出结构详解不只是字段列表而是可执行的数据库契约生成的 Markdown 文档目录结构如下以./docs/markdown/为例├── README.md # 总览数据库名、生成时间、表总数、统计摘要 ├── tables/ │ ├── user.md # 每张表独立文件 │ ├── order.md │ └── product.md ├── indexes/ # 独立索引说明含联合索引字段顺序 │ └── idx_user_status_created.md └── constraints/ # 外键、检查约束详情 └── fk_order_user_id.md打开tables/user.md你会看到# user 表说明 **数据库**: myapp_db nbsp; **引擎**: InnoDB nbsp; **字符集**: utf8mb4 nbsp; **生成时间**: 2024-05-20 14:22:36 | 字段名 | 类型 | 允许为空 | 默认值 | 键 | 注释 | |--------|------|----------|--------|----|------| | id | BIGINT | ❌ | NULL | PRI | 用户ID | | name | VARCHAR(50) | ❌ | NULL | | 用户名 | | status | TINYINT | ✅ | 0 | | 状态0-禁用,1-启用 | | created_at | DATETIME | ✅ | CURRENT_TIMESTAMP | | 创建时间 | **索引** - PRIMARY KEY (id) - KEY idx_user_status (status) **建表语句** sql CREATE TABLE user ( id bigint NOT NULL COMMENT 用户ID, name varchar(50) NOT NULL COMMENT 用户名, status tinyint DEFAULT 0 COMMENT 状态0-禁用,1-启用, created_at datetime DEFAULT CURRENT_TIMESTAMP COMMENT 创建时间, PRIMARY KEY (id), KEY idx_user_status (status) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4 COMMENT用户主表;注意允许为空 列用 ❌/✅ 直观表示 NOT NULL/NULL键 列用 PRI/MUL/UNI 标准缩写所有注释COMMENT原样保留**包括中文标点和括号里的枚举说明**——这正是它比手工整理靠谱的地方。 --- ## 4. 避坑指南那些让我重装三次 MySQL 驱动才搞懂的边界问题 ### 4.1 现象MySQL 8.0 连接报错 Public Key Retrieval is not allowed **原因**MySQL 8.0 默认开启 caching_sha2_password 认证插件而老版本 JDBC 驱动 8.0.28未启用公钥检索。工具内置驱动版本若偏低就会卡在这里。 **解决** - 方案 A推荐升级 jar 包到 v2.3.0已内置 MySQL 8.0.33 驱动 - 方案 B在 JDBC URL 末尾加参数 allowPublicKeyRetrievaltrueuseSSLfalse - 方案 C治本登录 MySQL将 doc_reader 用户认证方式降级 sql ALTER USER doc_reader% IDENTIFIED WITH mysql_native_password BY your_secure_password; FLUSH PRIVILEGES;4.2 现象PostgreSQL 表注释为空字段注释正常原因PostgreSQL 的表级注释存储在pg_description系统表但需关联pg_class和pg_namespace。某些精简版 PostgreSQL如某些云厂商 RDS可能未开启pg_catalog权限或doc_reader账号缺少SELECT ON pg_description权限。解决给账号加权限DBA 执行GRANT SELECT ON pg_description TO doc_reader; GRANT SELECT ON pg_class TO doc_reader; GRANT SELECT ON pg_namespace TO doc_reader;或改用--sql-file模式让 DBA 在导出 SQL 时用COMMENT ON TABLE user IS 用户主表;显式写出注释。4.3 现象Word 输出的表格文字挤在一起没有换行原因Apache POI 对中文自动换行支持较弱尤其当字段注释含长中文句如COMMENT 订单状态0-待支付,1-已支付,2-已发货,3-已完成,4-已取消,5-已退款POI 默认不折行。解决在配置文件config.yaml中增加word节点参数word: auto-wrap: true # 启用单元格自动换行 font-size: 10 # 调小字号提升可读性 table-width-ratio: 0.95 # 表格占页面宽度比例避免超宽更彻底修改 Word 模板company-template.docx选中表格 → 右键「表格属性」→ 「单元格」→ 勾选「自动换行」。4.4 现象Oracle 数据库生成的字段类型全是VARCHAR2丢失长度信息原因Oracle 的USER_TAB_COLUMNS.DATA_LENGTH返回字节长度而DATA_TYPE为VARCHAR2时实际字符长度需结合CHAR_USEDC字符语义判断。旧版工具解析逻辑未区分字节/字符语义。解决升级到 v2.2.0已修复 Oracle 类型解析能正确输出VARCHAR2(50 CHAR)若无法升级临时方案在 Oracle 中创建视图暴露字符长度CREATE OR REPLACE VIEW docgen_columns AS SELECT table_name, column_name, data_type, CASE WHEN char_used C THEN data_length ELSE data_length/2 END AS char_length, nullable, comments FROM user_tab_cols t JOIN user_col_comments c USING(table_name,column_name);然后在配置中指定--sql-file用此视图生成。4.5 现象生成的 Markdown 中TEXT类型字段显示为LONGTEXT与实际不符原因MySQL 的TEXT、MEDIUMTEXT、LONGTEXT在information_schema.COLUMNS.COLUMN_TYPE中统一返回text工具靠COLUMN_TYPE字段无法区分。解决工具 v2.3.0 已优化改用information_schema.COLUMNS.EXTRA和COLUMN_COMMENT辅助判断但最准的方式是查SHOW CREATE TABLE结果强制使用--sql-file模式确保原始 DDL 中类型名完整或在配置中添加类型映射高级用法type-mapping: mysql: text: TEXT mediumtext: MEDIUMTEXT longtext: LONGTEXT5. 进阶实战把它塞进 GitLab CI让每次 DDL 提交自动触发文档更新5.1 场景还原我们如何实现“代码即文档”的闭环在某跨平台系统的 DevOps 流程中数据库变更必须走 SQL 脚本管理所有 DDL 存于./sql/migrations/目录按V1.0.0__init.sql、V1.1.0__add_is_deleted_to_user.sql命名。过去靠人工跑 docgen总有遗漏。现在我们让 GitLab CI 在每次向main分支 push SQL 文件时自动下载最新版 database-doc-generator解析本次提交新增/修改的 SQL 文件生成 Markdown 文档提交到docs/目录并推送到仓库。这样开发者git push完 SQL10 分钟后在线文档站就刷新了新字段说明——文档和代码永远同 commit hash。5.2 CI 配置文件详解.gitlab-ci.yml关键片段stages: - docgen generate-db-doc: stage: docgen image: openjdk:11-jre-slim before_script: - apt-get update apt-get install -y curl unzip rm -rf /var/lib/apt/lists/* - export DOCGEN_JARdatabase-doc-generator-2.3.1.jar - export DOCGEN_URLhttps://github.com/xxx/database-doc-generator/releases/download/v2.3.1/${DOCGEN_JAR} - curl -L ${DOCGEN_URL} -o ${DOCGEN_JAR} script: # 1. 找出本次 MR/commit 中变动的 SQL 文件 - | if [ $CI_PIPELINE_SOURCE merge_request_event ]; then CHANGED_SQL$(git diff --name-only $CI_MERGE_REQUEST_TARGET_BRANCH_NAME...$CI_COMMIT_SHA -- sql/migrations/*.sql | head -20) else CHANGED_SQL$(git diff --name-only $CI_COMMIT_BEFORE_SHA $CI_COMMIT_SHA -- sql/migrations/*.sql | head -20) fi echo Changed SQL files: $CHANGED_SQL # 2. 若有变动合并所有相关 SQL 到临时文件避免单文件解析缺失外键上下文 - | if [ -n $CHANGED_SQL ]; then mkdir -p ./tmp-ddl cat $CHANGED_SQL ./tmp-ddl/merged-ddl.sql # 3. 运行 docgen输出到 docs/db/ java -jar ${DOCGEN_JAR} \ --sql-file ./tmp-ddl/merged-ddl.sql \ --output-format markdown \ --output-dir ./docs/db/ \ --verbose # 4. 提交生成的文档仅当有改动 git config --global user.email ciexample.com git config --global user.name GitLab CI git add ./docs/db/ if git status --porcelain | grep -q ^M\|^A; then git commit -m [CI] Update DB docs for $(echo $CHANGED_SQL | tr \n | cut -c1-80) git push https://gitlab-ci-token:${CI_JOB_TOKEN}${CI_SERVER_HOST}/${CI_PROJECT_PATH}.git HEAD:${CI_DEFAULT_BRANCH} fi else echo No SQL files changed, skip docgen. fi only: - main - merge_requests关键点说明image: openjdk:11-jre-slim确保环境干净无 JDK 版本冲突curl -L ${DOCGEN_URL}直接下载 release避免构建缓存污染git diff ... -- sql/migrations/*.sql精准捕获 DDL 变更不扫无关文件cat $CHANGED_SQL merged-ddl.sql合并多文件让工具能识别跨表外键如order.user_id引用user.idgit push https://gitlab-ci-token:${CI_JOB_TOKEN}...使用 CI Token 推送无需额外配置 deploy key。5.3 文档质量守门员在 CI 中加入字段注释覆盖率检查光生成文档不够还要保证质量。我们在 CI 中加了一道检查所有非主键、非索引字段必须有 COMMENT。否则 pipeline 失败强制开发者补注释。# 在 generate-db-doc job 的 script 末尾添加 - | # 检查生成的 Markdown 中是否有字段缺失 COMMENT MISSING_COMMENT$(grep -r ^\|.*\|.*\|.*\|.*\|.*\|$ ./docs/db/tables/ | grep -v 注释 | awk -F\| {print $1,$2,$5} | grep -E \s\|\s\|\s\$ | wc -l) if [ $MISSING_COMMENT -gt 0 ]; then echo ERROR: Found $MISSING_COMMENT fields without COMMENT. Please add COMMENT to your DDL. echo Example: \name\ VARCHAR(50) NOT NULL COMMENT 用户名, exit 1 fi这段 Bash 会扫描所有tables/*.md文件找那些第 5 列注释列为空的行。一旦发现立即exit 1中断 pipeline并给出修复示例。从那以后我每次写 DDL都强制在CREATE TABLE语句里敲完字段后立刻补上COMMENT——不是因为流程要求而是因为 CI 会红着脸告诉你“这里缺注释不许过”。希望帮到你。本文还有配套的精品资源点击获取
