手で書くテーブル定義書が古くなる理由
テーブル定義書は、マイグレーションとは別のファイルとして Excel で管理されることが多いドキュメントです。列を 1 つ追加するたびに、DDL・ER 図・定義書の 3 か所を直す必要があり、どれか 1 つは必ず遅れます。リリースのたびに誰かが半日かけて書き直し、それでも細かい差分が漏れる。この繰り返しで、定義書は「参考程度」の資料になっていきます。
Joinery は、スキーマを 1 つの DBML ファイルで管理し、そこから定義書を生成します。手で書く場所がないので、ずれる余地がありません。
出力できる形式と内容
設計書タブで内容を確認し、Excel のテーブル定義書と、1 ファイルで完結する HTML の設計書の 2 形式で書き出せます。
| 項目 | 内容 |
|---|---|
| 表紙・改訂履歴 | 表題、システム名、作成者、版数、文書番号、改訂履歴（設定ファイルに書いた内容） |
| 目次・テーブル一覧 | TableGroup ごとにまとめたテーブルの一覧 |
| ER 図 | 図の配置をそのまま使った ER 図（HTML 版） |
| 列定義 | No、列名、データ型、長さ・精度、PK、FK（参照先）、NOT NULL、UNIQUE、既定値、説明 |
| インデックス・制約 | インデックス名、対象列（式）、PK・UNIQUE、種類、CHECK 制約 |
| 参照関係 | 参照先、カーディナリティ、ON DELETE / ON UPDATE |
説明欄には、DBML の Note に書いた内容を改行もそのまま載せます。DBML に独自の書き方を持ち込まないため、「論理名」の欄はありません。日本語名を載せたい場合は Note に書いてください。
既存の DB から定義書を作る手順
- スキーマを取り込む。開発用の PostgreSQL・MySQL・SQLite に読み取り専用で接続するか、DDL ファイル（PostgreSQL / MySQL / SQL Server / SQLite）を読み込みます。
- 説明を足す。テーブルや列に Note を書き足します。DB に付けたコメントは、取り込み時に Note として読み込みます。
- 書き出す。コマンドパレットから「設計書（Excel）」または「設計書（HTML）」を選びます。
保存のたびに自動で更新する
図の配置を保存している設定ファイル（.joinery.json）に出力先を書いておくと、アプリで保存するたびに定義書を書き出します。リポジトリの docs/ に置けば、プルリクエストに定義書の差分も一緒に載ります。
"doc": {
"title": "受注管理システム DB設計書",
"system": "受注管理",
"version": "1.2",
"autoExport": [
{ "format": "html", "path": "docs/db.html" },
{ "format": "xlsx", "path": "docs/db.xlsx" }
]
}初回だけ、そのプロジェクトで自動出力してよいかを確認します。隠しフォルダへの出力はしません。
CI で作る場合は、コマンドラインからも出力できます。
joinery docs schema.dbml --format xlsx -o docs/db.xlsxよくある質問
決まった書式の Excel に合わせられますか？
現在は Joinery の標準の書式で出力します。社内書式への差し込みには対応していません。
同じスキーマから毎回同じ定義書になりますか？
はい。生成に AI は使わず、決まったルールで作ります。生成日時を除けば毎回同じ内容になるので、HTML 版は Git で差分を確認できます。
どの DB に対応していますか？
実 DB からの取り込みは PostgreSQL・MySQL・SQLite、DDL ファイルからの取り込みは PostgreSQL・MySQL・SQL Server・SQLite に対応しています。