简介这是一款轻量级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 是什么一个轻量级数据库文档自动化生成器专治 PowerDesigner 太重、手工写文档太累、SQL 注释没人维护的三重焦虑你有没有遇到过这样的场景新同事入职想快速搞懂数据库里user_profile表为什么有status_v2和status_flag两个字段测试同学提 bug说「订单状态更新失败」你翻了三遍建表语句才想起order_status是 enum 类型但枚举值定义早被删在某个已合并的 PR 里上线前要交交付文档你对着 Navicat 一条条复制 DDL、粘贴到 Word、手动加中文注释、再调格式——结果发现created_at字段没写默认值但文档里写了DEFAULT CURRENT_TIMESTAMP而生产库实际是NULL。database-doc-generator 就是为这种「文档永远滞后于代码」的现实而生的它不依赖 ER 图、不启动 Java 运行时、不连线上库只读本地 SQL 文件或直连只读账号输入是干净的 DDLCREATE TABLE 语句输出是结构清晰、带字段注释、含索引/约束说明、可直接交付的 Markdown 和 Word 文档。它适合中小型团队、敏捷迭代项目、数据中台初期建设阶段——当你需要「今天改完表明天文档就同步发给产品和测试」而不是等 DBA 抽出半天时间打开 PowerDesigner 拉线建模。2. 从零跑通 database-doc-generator用最简方式生成一份可用的数据库文档2.1 环境准备与安装Python 3.8 pip5 分钟完成部署database-doc-generator 是一个纯 Python 工具无 GUI、无服务端、无后台进程本质是一个命令行脚本。它不依赖 Java避开 PowerDesigner 的 JVM 启动慢、不依赖 Node.js绕开前端工程化复杂度只要系统有 Python 3.8 或更高版本就能运行。常见 Linux/macOS 系统通常自带 Python 3.9Windows 用户推荐使用 python.org 官方安装包勾选 “Add Python to PATH”。验证是否就绪python --version # 输出应为 Python 3.8.10 或更高 pip list | grep doc-generator # 若无输出说明尚未安装安装命令极简注意不是pip install database-doc-generator包名实际为dbdocgenpip install dbdocgen提示若提示权限错误如 macOS 上的PermissionError请改用pip install --user dbdocgen。该工具无任何外部服务依赖安装后即可离线使用。安装成功后终端输入dbdocgen --help应显示完整参数列表包括--input、--output、--format等核心选项。这是整个流程的起点——没有配置文件、没有初始化向导、没有首次运行弹窗一切由命令驱动。2.2 输入源选择DDL 文件优先支持直连但强烈建议用文件database-doc-generator 支持两种输入方式✅推荐本地 DDL SQL 文件.sql例如schema_v2.3.sql内容为标准CREATE TABLE语句可含COMMENT ON COLUMN或 MySQL 风格的COMMENT 用户昵称⚠️可选数据库直连PostgreSQL / MySQL需提供--host、--port、--user、--password、--database参数。为什么首推 DDL 文件第一安全避免在 CI/CD 流水线中硬编码数据库密码第二可控DDL 文件本身是版本化资产Git 管理文档生成即“快照式”交付不会因线上库临时变更导致文档漂移第三兼容某些云数据库如阿里云 RDS 只读实例限制information_schema查询权限而 DDL 文件天然绕过此限制。假设你有一个mysql_ddl.sql内容节选如下CREATE TABLE user_account ( id bigint NOT NULL AUTO_INCREMENT COMMENT 主键ID, email varchar(255) NOT NULL COMMENT 邮箱唯一索引, status tinyint NOT NULL DEFAULT 1 COMMENT 状态1-启用0-禁用, PRIMARY KEY (id), UNIQUE KEY uk_email (email) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4 COMMENT用户账号主表;这个文件就是全部输入——无需额外元数据文件无需 JSON 描述无需 ER 图导出。2.3 最小可行命令生成 Markdown 文档只需一行有了 DDL 文件生成第一份文档只需一条命令dbdocgen --input mysql_ddl.sql --output docs/db_doc.md --format markdown执行后终端会输出类似✅ 已解析 12 张表 ✅ 已提取 87 个字段注释 ✅ 已识别 15 个索引含主键、唯一键、普通索引 ✅ Markdown 文档已生成docs/db_doc.md打开docs/db_doc.md你会看到结构化内容顶部总览数据库名自动从文件名或--database-name推断、表总数、字段总数、索引总数每张表独立章节表名、表注释、字段列表含类型、是否为空、默认值、注释、索引详情名称、类型、字段顺序、约束说明如CHECK (status IN (0,1))字段表格严格按 DDL 中定义顺序排列非按字母序——这对理解业务逻辑至关重要比如created_at总在updated_at前面。逻辑说明--format markdown指定输出为 GitHub 风格 Markdown兼容所有静态站点生成器如 Docsify、Docusaurus和企业知识库如语雀、飞书文档的 Markdown 导入。--output路径支持嵌套目录如docs/v2.3/便于按版本归档。2.4 进阶输出一键生成 Word 文档适配甲方交付场景很多团队内部用 Markdown但对外交付尤其给客户、审计、法务仍需.docx。database-doc-generator 内置python-docx渲染引擎无需 LibreOffice 或 Word 安装dbdocgen --input mysql_ddl.sql --output docs/db_doc.docx --format word生成的 Word 文档具备标准标题层级Heading 1为数据库名Heading 2为表名Heading 3为“字段列表”等子节字段表格自动设置边框、居中对齐、列宽自适应中文注释正常显示已内置 UTF-8 编码处理无乱码索引部分用项目符号列表区分主键PK、唯一键UK、普通索引IDX。参数说明--format word会自动启用更严格的排版逻辑——例如字段类型列固定宽度varchar(255)和bigint对齐、注释列自动换行、空值约束用 ✅/❌ 图标实际为 Unicode 字符非图片保证打印清晰。若需调整字体可在生成后手动修改 Word 模板工具不锁定样式方便定制。3. 核心参数详解3 个必调参数与 2 个隐藏技巧3.1--database-name显式指定库名避免从文件名猜错默认情况下database-doc-generator 会从输入文件名提取数据库名schema_prod.sql→prodorder_db_v1.sql→order_db_v1。但文件名常含版本号或环境标识如schema_202405_v3.2.sql此时推断出的库名为schema_202405_v3.2显然不合理。解决方案是显式传参dbdocgen --input schema_202405_v3.2.sql --database-name order_center --output docs/order_center.md为什么重要文档首页的「数据库概览」区块会显示此名称且所有表名前缀如order_center.user_order均基于此。若未指定又恰巧 DDL 中无CREATE DATABASE语句则表名将无库前缀影响跨库关联理解。3.2--include-tables与--exclude-tables精准控制文档覆盖范围大型数据库常含临时表tmp_*、日志表log_*、历史归档表user_profile_his这些不应出现在正式文档中。--include-tables支持逗号分隔的白名单--exclude-tables支持黑名单# 只生成 user_* 和 order_* 相关表 dbdocgen --input full_schema.sql --include-tables user_profile,user_account,order_main,order_item --output docs/core_tables.md # 排除所有日志表和临时表 dbdocgen --input full_schema.sql --exclude-tables log_%,tmp_%,audit_trace --output docs/production_tables.md注意%为通配符非正则匹配任意字符。log_%匹配log_login、log_paymenttmp_user不匹配tmp_user_v2因tmp_user无%为精确匹配。黑白名单不可同时使用否则报错。3.3--comment-style适配不同数据库的注释语法解决「注释不显示」玄学问题这是新手最容易翻车的点。MySQL 用COMMENT xxxPostgreSQL 用COMMENT ON COLUMN table.col IS xxxSQL Server 用sp_addextendedproperty而 DDL 文件常混用多种风格。database-doc-generator 默认尝试解析 MySQL 风格若失败则回退到通用正则。但某些特殊写法会导致注释丢失例如-- PostgreSQL 风格但写在 CREATE TABLE 内部非法但有人这么写 CREATE TABLE t ( id int, name text ) COMMENT ON COLUMN t.name IS 姓名; -- ❌ 错误位置parser 无法捕获此时需显式指定风格# 明确告诉工具这是 PostgreSQL DDL按 COMMENT ON 语法解析 dbdocgen --input pg_schema.sql --comment-style postgresql --output docs/pg_doc.md # 若 DDL 是 Oracle 风格COMMENT ON TABLE ...则用 dbdocgen --input ora_schema.sql --comment-style oracle --output docs/ora_doc.md当前支持风格mysql默认、postgresql、oracle、sqlserver、generic纯正则匹配COMMENT.*?[]([^]*)[]。generic模式最暴力但可能误匹配 SQL 注释-- COMMENT xxx慎用。3.4 隐藏技巧 1用--template自定义 Markdown 渲染逻辑工具内置 Jinja2 模板引擎允许替换默认模板。先导出默认模板到本地dbdocgen --dump-template markdown my_template.md.j2打开my_template.md.j2你会看到类似# {{ database_name }} 数据库文档 共 {{ tables|length }} 张表{{ total_columns }} 个字段 {% for table in tables %} ## {{ table.name }}{{ table.comment or 无注释 }} | 字段名 | 类型 | 允许空 | 默认值 | 注释 | |--------|------|--------|--------|------| {% for col in table.columns %} | {{ col.name }} | {{ col.type }} | {{ ✅ if col.nullable else ❌ }} | {{ col.default or - }} | {{ col.comment or - }} | {% endfor %} {% endfor %}修改后用--template my_template.md.j2指向它。你可以在每张表后加「关联说明」区块填入{{ table.foreign_keys }}需 DDL 含外键定义为status类字段自动添加枚举值说明正则提取DEFAULT 1 CHECK (status IN (0,1,2))插入公司 Logo 图片链接Markdown 语法。注意自定义模板必须保留{{ database_name }}、{{ tables }}等核心变量否则渲染失败。模板调试建议先用小 DDL 文件单表验证。3.5 隐藏技巧 2--output-dir批量生成多格式构建文档流水线当需同时交付 Markdown内部 Wiki、Word客户、PDF归档时不必重复运行三次。--output-dir会将所有格式输出到同一目录mkdir -p docs/v2.4 dbdocgen --input schema_v2.4.sql \ --output-dir docs/v2.4 \ --format markdown,word,pdf当前支持格式markdown、word、pdfPDF 依赖weasyprint需额外pip install weasyprint。生成后docs/v2.4/下会有db_doc.md、db_doc.docx、db_doc.pdf三个文件。CI/CD 中可直接cp -r docs/v2.4 $ARTIFACTS_DIR归档。4. 避坑指南5 条血泪经验总结专治生成失败、注释丢失、格式错乱4.1 现象生成的 Markdown 中字段注释全为空但 DDL 里明明写了COMMENT xxx原因DDL 文件编码不是 UTF-8而是 GBK 或 ISO-8859-1。Python 读取时解码失败注释字符串变成乱码正则匹配失效。解决用 VS Code 或 Notepad 将 DDL 文件另存为 UTF-8无 BOM。Linux 下可用iconv -f gbk -t utf-8 schema.sql schema_utf8.sql转换。验证file -i schema.sql应返回charsetutf-8。4.2 现象Word 文档打开报错「文件损坏」或字段表格错位成一长条原因python-docx对中文路径支持不稳定若--output路径含中文如文档/db.docx可能导致 XML 写入异常。解决确保--output路径全为 ASCII 字符如docs/db.docx。生成后再手动重命名为中文名。这是python-docx库的已知限制非本工具缺陷。4.3 现象--include-tables指定user%但user_profile和user_account都没出现原因--include-tables不支持通配符%仅支持精确表名逗号分隔。%是--exclude-tables的特有语法。解决改用--exclude-tables反向排除或升级到 v0.8.0后续版本计划支持--include-patterns。当前务实做法用grep -E ^CREATE TABLE (user_profile|user_account) schema.sql user_subset.sql预处理。4.4 现象PostgreSQL DDL 中COMMENT ON COLUMN语句被跳过字段注释为空原因COMMENT ON COLUMN必须在对应CREATE TABLE之后执行但 DDL 文件中若COMMENT语句在CREATE TABLE之前解析器无法建立关联。解决用脚本调整 DDL 顺序。简单版Linuxawk /^CREATE TABLE/{c1} /^COMMENT ON COLUMN/{if(c) print; next} {print} schema.sql fixed.sql该命令确保每个COMMENT ON COLUMN都紧跟在其所属表的CREATE TABLE之后。4.5 现象生成的 PDF 中中文显示为方块或字体极小原因weasyprint默认不嵌入中文字体系统字体路径未正确识别。解决安装思源黑体免费开源sudo apt install fonts-noto-cjkUbuntu或brew install --cask font-source-han-sansmacOS创建weasyprint.css文件font-face { font-family: Noto Sans CJK SC; src: local(Noto Sans CJK SC); } body { font-family: Noto Sans CJK SC, sans-serif; }运行时加参数dbdocgen --input schema.sql --format pdf --css weasyprint.css。提示PDF 生成较慢每页约 2–3 秒建议仅用于最终交付日常预览用 Markdown。5. 进阶实战把 database-doc-generator 接入 GitOps 流水线实现「提交 DDL 即发布文档」5.1 场景还原某中台团队的文档交付痛点某高校实验室开发的数据中台系统数据库由 3 名后端开发者共同维护。过去流程是开发者 A 修改user_profile.sql增加last_login_ip字段并加注释提 MRMerge Request时手动更新 Confluence 页面的「用户表字段说明」QA 测试时发现文档未更新反馈后 A 再次编辑 Confluence上线前DBA 从 Confluence 复制内容到 Word调整格式后邮件发送。平均每次表变更文档延迟 1–2 天且 Confluence 版本与代码库不同步。他们决定用 database-doc-generator 实现 GitOpsDDL 文件是唯一真相源文档是其衍生品由 CI 自动生成并推送。5.2 具体落地步骤4 个关键动作步骤 1规范 DDL 存放位置与命名在 Git 仓库根目录下建db/ddl/目录所有 DDL 按模块存放db/ddl/ ├── core/ # 核心业务表 │ ├── user.sql │ └── order.sql ├── log/ # 日志表不纳入正式文档 │ └── audit_log.sql └── versioned/ # 按版本归档供回溯 └── v2.3.sql约定core/下所有.sql文件参与文档生成log/下文件被--exclude-tables过滤。步骤 2编写 CI 脚本以 GitLab CI 为例在.gitlab-ci.yml中添加 jobgenerate-db-doc: stage: deploy image: python:3.9-slim before_script: - pip install dbdocgen weasyprint script: - mkdir -p public/docs # 生成 Markdown供内部 Wiki - dbdocgen --input db/ddl/core/ --output-dir public/docs/markdown --format markdown # 生成 Word供交付 - dbdocgen --input db/ddl/core/ --output-dir public/docs/word --format word # 生成 PDF供归档 - dbdocgen --input db/ddl/core/ --output-dir public/docs/pdf --format pdf --css docs/weasyprint.css artifacts: paths: - public/docs/ expire_in: 1 week only: - main关键点--input支持目录自动合并所有.sql文件--output-dir统一管理产物。artifacts使文档可下载only: main确保仅主干分支触发。步骤 3对接知识库以语雀为例语雀支持 Webhook 接收 Markdown 并自动发布。在 CI 脚本末尾添加after_script: - curl -X POST https://www.yuque.com/api/v2/repos/{repo_id}/docs \ -H X-Auth-Token: ${YUQUE_TOKEN} \ -F title数据库文档${CI_COMMIT_TAG:-main} \ -F slugdb-doc-${CI_COMMIT_SHORT_SHA} \ -F public1 \ -F body$(cat public/docs/markdown/db_doc.md) \ -F formatmarkdown注意${YUQUE_TOKEN}为 GitLab CI 变量加密存储{repo_id}替换为语雀知识库 ID。这样每次main分支有新提交语雀自动更新最新文档URL 不变slug固定旧链接不失效。步骤 4设置文档校验门禁Pre-commit Hook防止开发者提交无注释的 DDL。在项目根目录加.pre-commit-config.yamlrepos: - repo: https://github.com/pre-commit/pre-commit-hooks rev: v4.4.0 hooks: - id: check-yaml - repo: local hooks: - id: ddl-comment-check name: 检查 DDL 字段注释 entry: bash -c grep -q COMMENT $1 || { echo ERROR: $1 缺少 COMMENT 注释; exit 1; } language: system files: \.sql$ types: [file]开发者git commit时若user.sql无任何COMMENT提交被拒绝并提示「ERROR: user.sql 缺少 COMMENT 注释」。强制注释成为开发习惯。5.3 效果验证从「文档滞后」到「文档即代码」实施 3 周后该团队统计文档平均生成耗时2.3 秒12 张表87 字段文档与代码差异率从 37% 降至 0%CI 每次提交必生成无遗漏QA 反馈文档问题次数从每周 5–8 次降为 0新成员上手时间从平均 3 天缩短至 0.5 天直接看语雀最新文档字段注释即业务含义。最关键的是心态转变开发者不再视「写文档」为额外负担而是ALTER TABLE ADD COLUMN后顺手加一行COMMENT的自然动作——因为知道这行字下一秒就会变成 QA 测试依据、产品需求参考、审计检查项。我一般会在团队启动新项目时就把db/ddl/core/目录和.pre-commit-config.yaml作为脚手架的一部分初始化好。不是等文档出问题才补救而是从第一天就让文档和代码呼吸同频。database-doc-generator 不是万能胶但它把「文档应该是什么」这件事拉回了工程师熟悉的轨道可版本化、可自动化、可验证。希望帮到你。本文还有配套的精品资源点击获取
