據(jù)字典文檔生成：從表結(jié)構(gòu)到自動(dòng)化流水線)
DBeaver 數(shù)據(jù)字典文檔生成從表結(jié)構(gòu)到自動(dòng)化流水線【免費(fèi)下載鏈接】dbeaverFree universal database tool and SQL client項(xiàng)目地址: https://gitcode.com/GitHub_Trending/db/dbeaver如果表結(jié)構(gòu)已經(jīng)變了你手工維護(hù)的文檔永遠(yuǎn)追不上。DBeaver 本身就帶著數(shù)據(jù)轉(zhuǎn)移導(dǎo)出、ERD 圖、DDL 生成這三件套足夠你拼出一條數(shù)據(jù)字典文檔自動(dòng)生成流水線把庫(kù)里的元信息查出來(lái)導(dǎo)出成 Markdown再掛上定時(shí)任務(wù)文檔每天自己更新。文檔和表對(duì)不上號(hào)的時(shí)候上線前常見(jiàn)的一幕前端問(wèn)新訂單表有哪幾個(gè)字段你翻文檔文檔寫(xiě) 12 個(gè)字段實(shí)際表里有 16 個(gè)——要么有人加列沒(méi)報(bào)備要么加了列忘了改文檔。問(wèn)題不在誰(shuí)偷懶而在文檔是第二份拷貝任何第二份拷貝都會(huì)落后于原始數(shù)據(jù)。正確的做法是把數(shù)據(jù)庫(kù)當(dāng)成唯一事實(shí)源把文檔變成每次都可以重新生成的產(chǎn)物。DBeaver 的價(jià)值在于從讀結(jié)構(gòu)到落成文件中間的工具都現(xiàn)成。先認(rèn)全這三個(gè)右鍵菜單ERD 圖一圖看懂表間關(guān)系在數(shù)據(jù)庫(kù)導(dǎo)航器里選中一個(gè) schema 或若干張表右鍵選 ER Diagram字段、類型、外鍵關(guān)系會(huì)鋪成一張圖。給新人講這幾張表怎么關(guān)聯(lián)圖的效率遠(yuǎn)高于字段清單。ERD 編輯器的實(shí)現(xiàn)在 plugins/org.jkiss.dbeaver.ui.editors.erd/想改導(dǎo)出樣式可以順著看。數(shù)據(jù)轉(zhuǎn)移向?qū)П疚牡闹鹘怯益I一張表、一個(gè)視圖甚至一段查詢結(jié)果選 Export進(jìn)入數(shù)據(jù)轉(zhuǎn)移向?qū)?。第一步確認(rèn)導(dǎo)出對(duì)象第二步選輸出格式——Markdown、CSV、JSON、HTML、XML、SQL、TXT 各有獨(dú)立導(dǎo)出器最后一步預(yù)覽確認(rèn)再落盤(pán)。這些導(dǎo)出器的源碼在 plugins/org.jkiss.dbeaver.data.transfer/每種格式可選項(xiàng)表頭、引號(hào)、空值顯示、編碼都注冊(cè)在該目錄的 plugin.xml 里想知道某個(gè)格式能調(diào)什么參數(shù)翻那里最準(zhǔn)。Generate SQL結(jié)構(gòu)本身也能導(dǎo)出容易被忽略的菜單右鍵表Generate SQL DDL把建表語(yǔ)句輸出成 .sql 文件。對(duì)可復(fù)跑的文檔來(lái)說(shuō)DDL 比任何文字描述都更接近事實(shí)適合和字段清單放在一起歸檔。把字段清單導(dǎo)出成 MarkdownDBeaver 導(dǎo)出的是行數(shù)據(jù)而數(shù)據(jù)字典要的是表的元信息。思路不復(fù)雜先對(duì)數(shù)據(jù)庫(kù)自己的字典視圖寫(xiě)一條查詢?cè)侔巡樵兘Y(jié)果當(dāng)數(shù)據(jù)導(dǎo)出成 Markdown。以 MySQL 為例這條查詢把每張表的字段、類型、是否可空、默認(rèn)值、注釋一次性拉出來(lái)SELECT TABLE_NAME AS 表, COLUMN_NAME AS 字段, COLUMN_TYPE AS 類型, IS_NULLABLE AS 可空, COLUMN_DEFAULT AS 默認(rèn)值, COLUMN_COMMENT AS 注釋 FROM information_schema.COLUMNS WHERE TABLE_SCHEMA your-database ORDER BY TABLE_NAME, ORDINAL_POSITION;在 DBeaver 的 SQL 編輯器里執(zhí)行結(jié)果就是一張干凈的表格。接著右鍵結(jié)果網(wǎng)格選 Export格式挑 Markdown產(chǎn)出的 md 表格可以直接貼進(jìn) README 或 wiki。幾個(gè)實(shí)操細(xì)節(jié)勾選導(dǎo)出向?qū)Ю锱c列注釋相關(guān)的選項(xiàng)——注釋列是數(shù)據(jù)字典的魂丟了注釋文檔只剩一半價(jià)值按 schema 過(guò)濾再查詢別全庫(kù)拉字典視圖在大型庫(kù)里很占時(shí)間結(jié)果要喂給腳本解析時(shí)改導(dǎo)出 JSON比 md 好處理PostgreSQL、SQLite 的字典視圖名字不同但查詢形態(tài)一樣找本庫(kù)的列元信息表如 information_schema.columns、sqlite_master把列拼成一張清單即可。生成的 md 按docs/庫(kù)名/表名.md放進(jìn)倉(cāng)庫(kù)從此每次加列都能在 git diff 里看見(jiàn)——這一條本身就值回票價(jià)。把文檔生成掛進(jìn)定時(shí)任務(wù)一次性導(dǎo)出只是起點(diǎn)重點(diǎn)是之后不用你碰。最簡(jiǎn)形式是一個(gè)每日腳本拉 DDL、重生成字段清單、提交。DBeaver 的導(dǎo)出向?qū)еС职颜着渲帽４嫦聛?lái)重跑時(shí)不必重新選格式、重新調(diào)參數(shù)腳本里直接復(fù)用即可。#!/bin/bash # 每日更新數(shù)據(jù)字典文檔并提交 cd /path/to/database-docs mysqldump --no-data your-host:3306/your-database ddl.sql python3 gen_dict.py --db your-database --out tables/ git add . git commit -m auto: 更新數(shù)據(jù)字典 $(date %F) git push腳本干三件事dump DDL、重生成字段文檔、提交推送。丟進(jìn) cron 就行。想掛進(jìn) CI 的話一個(gè)定時(shí)觸發(fā)的 job 足夠name: update-db-docs on: schedule: - cron: 0 2 * * * jobs: docs: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - run: bash scripts/update-dict.sh這段配置只做一件事每天凌晨 2 點(diǎn)跑一次上面那個(gè)腳本。說(shuō)實(shí)話這部分最值得做當(dāng)文檔和表結(jié)構(gòu)不再各走各的文檔是不是最新的這個(gè)問(wèn)題就不存在了。調(diào)導(dǎo)出編碼、空值顯示與 DDL 漂移先確認(rèn)連接字符編碼是 utf8mb4 再導(dǎo)出——中文亂碼通常出在連接側(cè)不是導(dǎo)出編碼顯式設(shè)置 nullString 選項(xiàng)——空值在文檔里顯示成什么不設(shè)置很容易被誤讀成無(wú)默認(rèn)值大庫(kù)按 schema 分批導(dǎo)出再拼文件——全庫(kù)一次查詢又慢又容易超時(shí)固定 DDL 的單一來(lái)源——mysqldump 和 Generate SQL 輸出格式有細(xì)微差別diff 前先統(tǒng)一想繼續(xù)深入SQL 模型和方言相關(guān)的邏輯在 plugins/org.jkiss.dbeaver.model.sql/自己寫(xiě)字典查詢模板、處理各庫(kù)差異時(shí)翻源碼比猜快。下一步可以做的事挑一張核心表右鍵打開(kāi) ERD 圖發(fā)給團(tuán)隊(duì)替換掉舊字段表格把核心表的字段清單導(dǎo)出為 Markdown放進(jìn)倉(cāng)庫(kù) docs 目錄并提交在導(dǎo)出向?qū)Ю锕潭?nullString 與編碼設(shè)置保存整套配置供腳本復(fù)用把每日腳本掛進(jìn) cron先連續(xù)跑一周觀察 diff 量是否在預(yù)期內(nèi)文檔穩(wěn)定后接入 CI改成 schema 變更時(shí)觸發(fā)而不是純定時(shí)【免費(fèi)下載鏈接】dbeaverFree universal database tool and SQL client項(xiàng)目地址: https://gitcode.com/GitHub_Trending/db/dbeaver創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 DBeaver 數(shù)據(jù)字典文檔生成：從表結(jié)構(gòu)到自動(dòng)化流水線
DBeaver 數(shù)據(jù)字典文檔生成從表結(jié)構(gòu)到自動(dòng)化流水線【免費(fèi)下載鏈接】dbeaverFree universal database tool and SQL client項(xiàng)目地址: https://gitcode.com/GitHub_Trending/db/dbeaver如果表結(jié)構(gòu)已經(jīng)變了你手工維護(hù)的文檔永遠(yuǎn)追不上。DBeaver 本身就帶著數(shù)據(jù)轉(zhuǎn)移導(dǎo)出、ERD 圖、DDL 生成這三件套足夠你拼出一條數(shù)據(jù)字典文檔自動(dòng)生成流水線把庫(kù)里的元信息查出來(lái)導(dǎo)出成 Markdown再掛上定時(shí)任務(wù)文檔每天自己更新。文檔和表對(duì)不上號(hào)的時(shí)候上線前常見(jiàn)的一幕前端問(wèn)新訂單表有哪幾個(gè)字段你翻文檔文檔寫(xiě) 12 個(gè)字段實(shí)際表里有 16 個(gè)——要么有人加列沒(méi)報(bào)備要么加了列忘了改文檔。問(wèn)題不在誰(shuí)偷懶而在文檔是第二份拷貝任何第二份拷貝都會(huì)落后于原始數(shù)據(jù)。正確的做法是把數(shù)據(jù)庫(kù)當(dāng)成唯一事實(shí)源把文檔變成每次都可以重新生成的產(chǎn)物。DBeaver 的價(jià)值在于從讀結(jié)構(gòu)到落成文件中間的工具都現(xiàn)成。先認(rèn)全這三個(gè)右鍵菜單ERD 圖一圖看懂表間關(guān)系在數(shù)據(jù)庫(kù)導(dǎo)航器里選中一個(gè) schema 或若干張表右鍵選 ER Diagram字段、類型、外鍵關(guān)系會(huì)鋪成一張圖。給新人講這幾張表怎么關(guān)聯(lián)圖的效率遠(yuǎn)高于字段清單。ERD 編輯器的實(shí)現(xiàn)在 plugins/org.jkiss.dbeaver.ui.editors.erd/想改導(dǎo)出樣式可以順著看。數(shù)據(jù)轉(zhuǎn)移向?qū)П疚牡闹鹘怯益I一張表、一個(gè)視圖甚至一段查詢結(jié)果選 Export進(jìn)入數(shù)據(jù)轉(zhuǎn)移向?qū)?。第一步確認(rèn)導(dǎo)出對(duì)象第二步選輸出格式——Markdown、CSV、JSON、HTML、XML、SQL、TXT 各有獨(dú)立導(dǎo)出器最后一步預(yù)覽確認(rèn)再落盤(pán)。這些導(dǎo)出器的源碼在 plugins/org.jkiss.dbeaver.data.transfer/每種格式可選項(xiàng)表頭、引號(hào)、空值顯示、編碼都注冊(cè)在該目錄的 plugin.xml 里想知道某個(gè)格式能調(diào)什么參數(shù)翻那里最準(zhǔn)。Generate SQL結(jié)構(gòu)本身也能導(dǎo)出容易被忽略的菜單右鍵表Generate SQL DDL把建表語(yǔ)句輸出成 .sql 文件。對(duì)可復(fù)跑的文檔來(lái)說(shuō)DDL 比任何文字描述都更接近事實(shí)適合和字段清單放在一起歸檔。把字段清單導(dǎo)出成 MarkdownDBeaver 導(dǎo)出的是行數(shù)據(jù)而數(shù)據(jù)字典要的是表的元信息。思路不復(fù)雜先對(duì)數(shù)據(jù)庫(kù)自己的字典視圖寫(xiě)一條查詢?cè)侔巡樵兘Y(jié)果當(dāng)數(shù)據(jù)導(dǎo)出成 Markdown。以 MySQL 為例這條查詢把每張表的字段、類型、是否可空、默認(rèn)值、注釋一次性拉出來(lái)SELECT TABLE_NAME AS 表, COLUMN_NAME AS 字段, COLUMN_TYPE AS 類型, IS_NULLABLE AS 可空, COLUMN_DEFAULT AS 默認(rèn)值, COLUMN_COMMENT AS 注釋 FROM information_schema.COLUMNS WHERE TABLE_SCHEMA your-database ORDER BY TABLE_NAME, ORDINAL_POSITION;在 DBeaver 的 SQL 編輯器里執(zhí)行結(jié)果就是一張干凈的表格。接著右鍵結(jié)果網(wǎng)格選 Export格式挑 Markdown產(chǎn)出的 md 表格可以直接貼進(jìn) README 或 wiki。幾個(gè)實(shí)操細(xì)節(jié)勾選導(dǎo)出向?qū)Ю锱c列注釋相關(guān)的選項(xiàng)——注釋列是數(shù)據(jù)字典的魂丟了注釋文檔只剩一半價(jià)值按 schema 過(guò)濾再查詢別全庫(kù)拉字典視圖在大型庫(kù)里很占時(shí)間結(jié)果要喂給腳本解析時(shí)改導(dǎo)出 JSON比 md 好處理PostgreSQL、SQLite 的字典視圖名字不同但查詢形態(tài)一樣找本庫(kù)的列元信息表如 information_schema.columns、sqlite_master把列拼成一張清單即可。生成的 md 按docs/庫(kù)名/表名.md放進(jìn)倉(cāng)庫(kù)從此每次加列都能在 git diff 里看見(jiàn)——這一條本身就值回票價(jià)。把文檔生成掛進(jìn)定時(shí)任務(wù)一次性導(dǎo)出只是起點(diǎn)重點(diǎn)是之后不用你碰。最簡(jiǎn)形式是一個(gè)每日腳本拉 DDL、重生成字段清單、提交。DBeaver 的導(dǎo)出向?qū)еС职颜着渲帽４嫦聛?lái)重跑時(shí)不必重新選格式、重新調(diào)參數(shù)腳本里直接復(fù)用即可。#!/bin/bash # 每日更新數(shù)據(jù)字典文檔并提交 cd /path/to/database-docs mysqldump --no-data your-host:3306/your-database ddl.sql python3 gen_dict.py --db your-database --out tables/ git add . git commit -m auto: 更新數(shù)據(jù)字典 $(date %F) git push腳本干三件事dump DDL、重生成字段文檔、提交推送。丟進(jìn) cron 就行。想掛進(jìn) CI 的話一個(gè)定時(shí)觸發(fā)的 job 足夠name: update-db-docs on: schedule: - cron: 0 2 * * * jobs: docs: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - run: bash scripts/update-dict.sh這段配置只做一件事每天凌晨 2 點(diǎn)跑一次上面那個(gè)腳本。說(shuō)實(shí)話這部分最值得做當(dāng)文檔和表結(jié)構(gòu)不再各走各的文檔是不是最新的這個(gè)問(wèn)題就不存在了。調(diào)導(dǎo)出編碼、空值顯示與 DDL 漂移先確認(rèn)連接字符編碼是 utf8mb4 再導(dǎo)出——中文亂碼通常出在連接側(cè)不是導(dǎo)出編碼顯式設(shè)置 nullString 選項(xiàng)——空值在文檔里顯示成什么不設(shè)置很容易被誤讀成無(wú)默認(rèn)值大庫(kù)按 schema 分批導(dǎo)出再拼文件——全庫(kù)一次查詢又慢又容易超時(shí)固定 DDL 的單一來(lái)源——mysqldump 和 Generate SQL 輸出格式有細(xì)微差別diff 前先統(tǒng)一想繼續(xù)深入SQL 模型和方言相關(guān)的邏輯在 plugins/org.jkiss.dbeaver.model.sql/自己寫(xiě)字典查詢模板、處理各庫(kù)差異時(shí)翻源碼比猜快。下一步可以做的事挑一張核心表右鍵打開(kāi) ERD 圖發(fā)給團(tuán)隊(duì)替換掉舊字段表格把核心表的字段清單導(dǎo)出為 Markdown放進(jìn)倉(cāng)庫(kù) docs 目錄并提交在導(dǎo)出向?qū)Ю锕潭?nullString 與編碼設(shè)置保存整套配置供腳本復(fù)用把每日腳本掛進(jìn) cron先連續(xù)跑一周觀察 diff 量是否在預(yù)期內(nèi)文檔穩(wěn)定后接入 CI改成 schema 變更時(shí)觸發(fā)而不是純定時(shí)【免費(fèi)下載鏈接】dbeaverFree universal database tool and SQL client項(xiàng)目地址: https://gitcode.com/GitHub_Trending/db/dbeaver創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考