テーブル定義書は、データベースのテーブルごとに、カラムの論理名・物理名・型・桁・必須・既定値・キーを一覧にした設計書です。ER図がテーブル同士の関係を表すのに対し、テーブル定義書は1つのテーブルの中身を列単位で決めます。この記事では、記載項目をテーブル単位とカラム単位に分けて示したうえで、Excelで手書きした定義書がDDLとずれる原因と、DDLや稼働中のデータベースから定義書を自動生成する方法が、この記事の解説対象です。生成には、標準ライブラリだけで動くPythonスクリプト(実行結果つき)、PostgreSQLのシステムカタログ、OSSのtblsとSchemaSpyを使います。
まとめ:テーブル定義書はDDLを正本にし記載項目を自動生成で埋める
テーブル定義書に必要な項目は、テーブル単位の論理名・物理名・概要・キーと、カラム単位の論理名・物理名・型・桁・必須・既定値・キー・説明です。この中で人が考えて書く必要があるのは、論理名と説明だけです。型や必須、キーはDDLにすでに書かれています。
そこで、論理名と説明をCOMMENT ONでデータベースのコメントに持たせ、定義書はDDLや稼働中のDBから生成する形に切り替えます。稼働中のDBがあるならtblsで生成し、CIで tbls diff と tbls lint を回せば、更新漏れと論理名の書き忘れを機械で止められる仕組みです。Excelで手書きを続けてよいのは、DBがまだ無い要件定義の段階と、納品形式がExcelに決まっていて変えられない案件に限ります。後者でもtblsはxlsxを出力できるので、手で写す必要はありません。
テーブル定義書の記載項目:テーブル単位とカラム単位で書く内容の一覧
テーブル定義書の項目はプロジェクトごとに少しずつ違いますが、骨格は共通です。1シート(または1ページ)に1テーブルを置き、上段にテーブル全体の情報、下段にカラムの一覧を書きます。
テーブル単位の項目:論理名・物理名・概要・主キー・インデックスの書き方
上段に書くのは、テーブルの論理名(「受注」)、物理名(orders)、概要、主キー、インデックス、外部キーの一覧です。概要には「1行が何を表すか」を1文で書きます。「受注1件につき1行。取消しても行は消さず状態を変える」のように、行の単位と消し方まで書いておくと、後から読む人が論理削除の有無で迷いません。
インデックスは、名前・対象カラム・一意かどうかを並べます。サンプルDDLの idx_orders_customer なら「orders.customer_id/非一意」です。定義書を手で書く現場では、インデックスが最も書き漏れやすい項目です。DDLから生成する方式なら、この漏れは構造的に起きません。
カラム単位の8項目と型・桁・必須・既定値を書くときの判断基準
カラムの一覧には、次の8列を置くのが一般的です。左から順に、人が決める度合いの高い項目を並べています。
| 項目 | 記入例 | 決め方 |
|---|---|---|
| No | 4 | DDLの列順と一致させる |
| 論理名 | 合計金額(税込) | 業務用語で書き単位も含める |
| 物理名 | total_amount | 命名規約に従う英小文字 |
| 型・桁 | numeric(12,2) | 金額は浮動小数点型を避ける |
| 必須 | ○ | NOT NULL制約と一致させる |
| 既定値 | 0 | DEFAULT句をそのまま書く |
| キー | PK・UQ・FK | 制約から機械的に決まる |
| 説明 | 値引き後・送料込み | 計算方法や値の範囲を書く |
実務でまず埋めるべきは論理名と説明の2列です。型・必須・既定値・キーの4列はDDLに書いた時点で確定し、定義書側で別の値を書く理由がありません。ここを手で写すから、DDLとのずれが生まれます。型の選び方や制約の種類そのものはデータベースの属性とは?カラム・フィールド・項目の違いと種類・制約で詳しく扱っています。
論理名と物理名の対応表と命名規約をテーブル定義書の冒頭に置く理由
テーブル定義書の表紙か最初のシートには、命名規約と略語の対応表を置きます。amt と amount、dt と date が混ざると、同じ意味のカラムが別名で増えていくためです。「金額=amount」「日付=_date、日時=_at」「区分=_type」のように、論理名の語尾と物理名の接尾辞を1対1で決めます。
この対応表があれば、レビューで物理名を見ただけで規約違反に気づけます。後述するtblsの lint にも、すべてのテーブルに特定のカラムを必須にする requireColumns のような規則があり、規約の一部は機械判定に移せます。
テーブル定義書とER図・CRUD図・DDLの役割分担と作成する設計工程
データベースまわりの設計書は似た情報を別の切り口で持っています。重複して書くと、どれかが古くなります。担当範囲を先に決めておくのが、ずれを防ぐ一番の手です。
ER図は関係、定義書は列の詳細、DDLは実装を受け持つ対応表
| 設計書 | 受け持つ情報 | 読む人 |
|---|---|---|
| ER図 | テーブル間の関係と多重度 | 発注者・設計者 |
| テーブル定義書 | 列の論理名・型・制約・説明 | 開発者・保守担当 |
| CRUD図 | どの機能がどの表を読み書きするか | 設計者・試験担当 |
| DDL | 実際に作るテーブルと制約 | データベース |
テーブル定義書は、ER図のエンティティを1つずつ開いて列の中身を決めたものです。ER図に属性まで書き込む記法もありますが、型や既定値まで載せると図が読めなくなります。関係はER図、列の詳細は定義書と分けるのが無難です。ER図の書き方はER図とは?記号・線の読み方と書き方の手順、機能との対応はCRUD図の書き方:ER図と機能一覧から作る手順で解説しています。
基本設計と詳細設計のどちらで作るかと発注者の承認範囲の決め方
論理名・主キー・主要な列を決めるのは基本設計、型・桁・インデックスまで確定させるのは詳細設計、という分け方が一般的です。同じ定義書を工程ごとに書き足していく形になります。基本設計の段階で桁まで決めようとすると、画面設計の変更に引きずられて何度も書き直しになります。
発注者の承認範囲は、論理名と業務上の意味(説明列)までにとどめるのが現実的です。型や桁の妥当性は開発側の責任範囲として、レビューは社内で済ませます。基本設計の成果物全体の中での位置づけは基本設計とは?どこまで決めるか・成果物一覧が参考になります。
Excelで手書きした定義書がDDLとずれる原因と正本をDDLに置く判断
テーブル定義書をExcelで書き、それを見ながらDDLを書く。多くの現場はこの順で始めます。問題は、運用に入ってからの改修でDDLだけが先に変わることです。
定義書とDDLの二重管理で改修時に起きる型・桁・必須のずれの典型例
手書きの定義書で起きるずれは、ほぼ次の4種類に分かれます。上ほど頻度が高く、見つけにくいものです。
- 桁の拡張が定義書に反映されない:
varchar(50)を緊急対応で100に広げ、定義書は50のまま残る - 追加したカラムが定義書に無い:マイグレーションで列を足し、定義書の更新を後回しにして忘れる
- インデックスが定義書に無い:性能対策で本番に直接追加し、DDLの管理からも漏れる
- 必須の変更が逆になる:NULLを許すよう変えたのに、定義書の「必須」に○が残る
どれも、正しい値はデータベースの中にあります。ずれた定義書を信じて改修すると、桁あふれやNOT NULL違反として試験で初めて発覚します。そのため、正本はDDL(または稼働中のDB)に置き、定義書はそこから作る側に回すのが筋です。
正本をDDLに置き論理名をCOMMENT ONでデータベースに持たせる方法
DDLを正本にしたとき、DDLに無い情報は論理名と説明だけです。これはデータベースのコメント機能に入れられます。PostgreSQLでは COMMENT文 でテーブルとカラムにコメントを付けられ、NULL か空文字列を指定するとコメントは消えます。
CREATE TABLE orders (
order_id integer PRIMARY KEY,
customer_id integer NOT NULL REFERENCES customers (customer_id),
order_date date NOT NULL,
total_amount numeric(12,2) NOT NULL DEFAULT 0,
status varchar(20) NOT NULL DEFAULT 'received',
note text
);
CREATE INDEX idx_orders_customer ON orders (customer_id);
COMMENT ON TABLE orders IS '受注';
COMMENT ON COLUMN orders.order_id IS '受注ID';
COMMENT ON COLUMN orders.total_amount IS '合計金額(税込)';
コメントはpsqlの \d 系のコマンドで表示されるほか、obj_description・col_description という組み込み関数で取り出せます。MySQLはCOMMENT ONを持たず、CREATE TABLE の列定義に COMMENT '受注ID' と書く方式で、INFORMATION_SCHEMA.COLUMNS の COLUMN_COMMENT 列がコメントの取得元です。どちらの方式でも、論理名をDDLと同じファイルに置けば、マイグレーションのレビューで論理名の変更も一緒に確認できます。
DDLからテーブル定義書を生成するPythonスクリプトと実行結果
まだデータベースを立てていない段階でも、DDLファイルさえあれば定義書は作れます。ここではPythonの標準ライブラリだけで、DDLからMarkdownの定義書を出すスクリプトを示します。
標準ライブラリだけでDDLを読みMarkdownの定義書を出すスクリプト全文
DDLをメモリ上のSQLiteに流し込み、SQLiteのPRAGMAで列・外部キー・一意制約を取り出します。結果を返すPRAGMAは、SQLite 3.16.0以降なら pragma_table_xinfo('orders') のように表関数としてSELECT文から呼べる仕様です。COMMENT ONはSQLiteが解釈しないため、正規表現で先に抜き出して論理名の辞書にしています。
import re
import sqlite3
import sys
from pathlib import Path
# DDL(CREATE TABLE と COMMENT ON)からテーブル定義書をMarkdownで出す
COMMENT = re.compile(r"comment\s+on\s+(table|column)\s+([\w.]+)\s+is\s+'((?:[^']|'')*)'\s*;", re.I)
def load(ddl):
comments = {}
for kind, name, text in COMMENT.findall(ddl):
comments[name.lower()] = text.replace("''", "'")
body = COMMENT.sub("", ddl) # SQLiteはCOMMENT ONを解釈しないので外す
db = sqlite3.connect(":memory:")
db.executescript(body)
return db, comments
def table_doc(db, comments, table):
cols = db.execute(f"SELECT name, type, \"notnull\", dflt_value, pk FROM pragma_table_xinfo('{table}')").fetchall()
fks = {r[3]: f"{r[2]}.{r[4]}" for r in db.execute(f"SELECT * FROM pragma_foreign_key_list('{table}')")}
uniq = set()
for _, idx, unique, origin, _ in db.execute(f"SELECT * FROM pragma_index_list('{table}')"):
if unique and origin == "u":
uniq.update(r[2] for r in db.execute(f"SELECT * FROM pragma_index_info('{idx}')"))
lines = [f"## {comments.get(table, '(論理名なし)')}({table})", "",
"| No | 論理名 | 物理名 | 型 | 必須 | 既定値 | キー |",
"|---|---|---|---|---|---|---|"]
missing = []
for no, (name, typ, notnull, default, pk) in enumerate(cols, 1):
logical = comments.get(f"{table}.{name}".lower())
if logical is None:
missing.append(name)
keys = [k for k, on in (("PK", pk), ("UQ", name in uniq), (f"FK→{fks.get(name)}", name in fks)) if on]
required = "○" if notnull or pk else ""
lines.append(f"| {no} | {logical or ''} | {name} | {typ} | {required} | {default or ''} | {' '.join(keys)} |")
return "\n".join(lines), missing
def main(path):
db, comments = load(Path(path).read_text(encoding="utf-8"))
tables = [r[0] for r in db.execute("SELECT name FROM sqlite_schema WHERE type = 'table' ORDER BY name")]
for table in tables:
doc, missing = table_doc(db, comments, table)
print(doc + "\n")
for col in missing:
print(f"# 論理名なし: {table}.{col}", file=sys.stderr)
if __name__ == "__main__":
main(sys.argv[1] if len(sys.argv) > 1 else "schema.sql")
一意制約は、pragma_index_list の作成元が u(UNIQUE制約)のインデックスだけを拾って「UQ」と表示します。主キーは同じ一覧で pk と区別されるため、PKとUQが二重に付くことはありません。
サンプルDDLの実行結果と論理名の抜けを標準エラーで検出する例
前の章のordersに、顧客テーブルcustomersを加えたDDLを schema.sql として保存し、Python 3.14とSQLite 3.50の環境で実行した結果です。ordersの note 列だけ、わざとCOMMENT ONを書いていません。
$ python tabledef.py schema.sql
# 論理名なし: orders.note
## 顧客(customers)
| No | 論理名 | 物理名 | 型 | 必須 | 既定値 | キー |
|---|---|---|---|---|---|---|
| 1 | 顧客ID | customer_id | INTEGER | ○ | | PK |
| 2 | 顧客名 | customer_name | varchar(100) | ○ | | |
| 3 | メールアドレス | email | varchar(254) | ○ | | UQ |
| 4 | 登録日時 | created_at | timestamp | ○ | CURRENT_TIMESTAMP | |
## 受注(orders)
| No | 論理名 | 物理名 | 型 | 必須 | 既定値 | キー |
|---|---|---|---|---|---|---|
| 1 | 受注ID | order_id | INTEGER | ○ | | PK |
| 2 | 顧客ID | customer_id | INTEGER | ○ | | FK→customers.customer_id |
| 3 | 受注日 | order_date | date | ○ | | |
| 4 | 合計金額(税込) | total_amount | numeric(12,2) | ○ | 0 | |
| 5 | 受注状態 | status | varchar(20) | ○ | 'received' | |
| 6 | | note | TEXT | | | |
先頭の1行は標準エラーへの出力で、論理名の書き忘れを指摘しています。CIでこの行の有無を判定すれば、論理名の無いカラムを含む変更をマージ前に止めることが可能です。この環境のSQLiteは integer と text を大文字で返しましたが、varchar(100) や numeric(12,2) は書いたとおりに残っています。型名の大文字小文字を定義書でそろえたい場合は、出力時に変換を1行足してください。
この方式はDDLの文法がSQLiteで通る範囲に限られます。PostgreSQL固有の型(jsonb など)は型名の文字列として通りますが、GENERATED ALWAYS AS IDENTITY などSQLiteに無い構文は通りません。その場合は、次に示す稼働中DBからの取得に切り替えます。
稼働中のPostgreSQLからシステムカタログで定義書の行を取るSQL
開発用のDBが立っているなら、カタログから直接取るほうが正確です。列の情報は pg_attribute にあり、型名と桁は format_type・col_description などのシステム情報関数で人が読める形に直せます。
SELECT c.relname AS table_name,
obj_description(c.oid, 'pg_class') AS table_logical,
a.attnum AS no,
col_description(c.oid, a.attnum) AS logical_name,
a.attname AS column_name,
format_type(a.atttypid, a.atttypmod) AS data_type,
a.attnotnull AS not_null,
pg_get_expr(d.adbin, d.adrelid) AS default_value,
EXISTS (SELECT 1 FROM pg_constraint k
WHERE k.conrelid = c.oid AND k.contype = 'p'
AND a.attnum = ANY (k.conkey)) AS is_pk
FROM pg_class c
JOIN pg_namespace n ON n.oid = c.relnamespace
JOIN pg_attribute a ON a.attrelid = c.oid AND a.attnum > 0 AND NOT a.attisdropped
LEFT JOIN pg_attrdef d ON d.adrelid = c.oid AND d.adnum = a.attnum
WHERE n.nspname = 'public' AND c.relkind IN ('r', 'p')
ORDER BY c.relname, a.attnum;
information_schema.columns を使わずにカタログを直接読んでいるのは、コメントを取る関数がテーブルのOIDと列番号を引数に取るためです。なお information_schema.columns は、接続ユーザーが所有者か何らかの権限を持つテーブルの列しか返しません。定義書の生成には、全テーブルを読める権限のユーザーで接続してください。attisdropped で削除済みの列を除外している点も、列番号に欠けが出る理由として押さえておくと結果を読み違えません。
tblsとSchemaSpyで稼働中のデータベースから定義書を自動生成する手順
SQLを自分で保守したくないなら、OSSの生成ツールに任せます。代表的なのはtblsとSchemaSpyの2つで、出力の形と得意な運用が違います。
tblsの導入と.tbls.ymlの設定でMarkdownとExcelの定義書を出す手順
tblsはGo製のCLIで、2026年11月時点の最新リリースはv1.96系です。PostgreSQL・MySQL・MariaDB・SQLite・SQL Server・BigQuery・Redshiftなどに対応し、Homebrew(brew install tbls)、go install、Dockerイメージのいずれかで導入できます。設定はリポジトリ直下の .tbls.yml に書きます。
# .tbls.yml
dsn: postgres://dbuser:dbpass@localhost:5432/dbname?sslmode=disable
docPath: doc/schema
lint:
requireColumnComment:
enabled: true
comments:
- table: orders
columnComments:
note: 備考(社内メモ。顧客には表示しない)
$ tbls doc # docPath にテーブルごとのMarkdownとER図を出力
$ tbls out -t xlsx -o schema.xlsx # 同じ内容をExcelで出力
$ tbls doc --rm-dist # テーブル削除後は出力先を空にしてから再生成
論理名はデータベースのコメントから読まれます。.tbls.yml の comments に書いた値はスキーマ側のコメントより優先されるため、DBに手を入れにくい既存システムでは設定ファイル側で論理名を補うことが可能です。--force は既存の出力を上書きしますが、削除したテーブルのファイルは残ります。テーブルを消した後に使うのは --rm-dist です。接続文字列は環境変数 TBLS_DSN でも渡せるので、パスワードを設定ファイルに書かずに済みます。
tbls lintとtbls diffをCIで回して定義書の更新漏れを止める設定
tblsのREADMEは、CIで tbls diff か tbls lint を実行してドキュメントの更新を確認する使い方を勧めています。tbls diff はデータベースと生成済みドキュメントの差分を表示し、tbls lint は lint に書いた規則でスキーマを検査します。
導入の順番は、まず requireColumnComment だけを有効にすることです。既存システムでは最初の実行で数百件の指摘が出ることも珍しくありません。その場合は新しく足すテーブルにだけ規則を当て、既存分は tbls coverage でコメントの充足率を測りながら段階的に埋めます。外部キーにインデックスを要求する requireForeignKeyIndex は、性能事故の予防になるので2番目に入れる価値があります。
SchemaSpyでER図付きのHTML定義書を出す場合の前提と使い分け
SchemaSpyはJava製で、ER図を含むHTMLのサイトを生成します。公式のインストール手順によると、動作にはJava 8以上が必要です。6.1.0以降はviz.jsを同梱し、-vizjs 引数を付ければGraphvizを入れずにER図を描けます。DockerイメージにはMySQL・MariaDB・PostgreSQL・SQL Server(jTDS)のJDBCドライバが入っています。
| 観点 | tbls | SchemaSpy | 自作スクリプト |
|---|---|---|---|
| 出力形式 | Markdown・xlsx・Mermaid等 | HTML(ER図つき) | 自由 |
| 実行環境 | 単体バイナリ | Java 8以上 | Python等 |
| CIでの差分検出 | diff・lintを標準装備 | 標準では無い | 自分で書く |
| DB無しで生成 | 不可 | 不可 | DDLから可 |
リポジトリでMarkdownを差分管理し、プルリクエストでレビューするならtblsを選びます。SchemaSpyは、社内のWebサーバーに置いたHTMLを非エンジニアも含めて閲覧する用途向けのツールです。DBを立てられない段階では、どちらも使えないので自作スクリプトで補います。
テーブル定義書を自動生成に切り替える条件とExcelで手書きを続ける場面
自動生成は万能ではありません。切り替えるかどうかは、DBが存在するかと、納品物の形式を誰が決めているかで判断します。
稼働中DBがあり改修が続く案件は自動生成に切り替えて保守する
稼働中のデータベースがあり、今後もテーブル変更が続くなら、迷わず自動生成に切り替えます。手書きの定義書は、改修のたびにDDLとずれる構造から抜け出せません。切り替えの初回は、既存のExcelから論理名を拾ってCOMMENT ONか .tbls.yml に移す作業が中心です。ここは一度きりの工数として見積もります。
テーブル数が多く、既存の定義書がどこまで正しいか分からない状態から始めるなら、現行DBの調査と設計の見直しを一緒に進めるほうが早く終わります。社内に手が足りなければ、データベース設計・移行支援のように現行DBの調査から引き受ける外部の手を借りるのも1つの方法です。
DBが未構築の要件定義段階と納品形式がExcel指定の案件の扱い
DBがまだ無い要件定義の段階では、Excelやスプレッドシートで論理名と説明を先に固めて構いません。ただし型と桁は空欄にしておき、基本設計でDDLを書き始めた時点で、正本をDDLに移します。その後Excelを編集し続けると、二重管理に戻ります。
契約で納品形式がExcelの定義書と決まっている案件は、手で書かずに tbls out -t xlsx で出力します。発注者指定のテンプレートと列の並びが違う場合も、生成したxlsxから値を貼り替える作業は数十分で済みます。手書きは選びません。ここで手書きに戻ると、納品後の改修でずれが再発します。設計書全般の書き分けは仕様書とは?種類と書き方・記載項目テンプレートで整理しています。
よくある質問
テーブル定義書の書き方や自動生成について、よく寄せられる質問に答えます。
テーブル定義書のテンプレートはどこで手に入りますか?
決まった公式様式はありません。記事中の8項目(No・論理名・物理名・型と桁・必須・既定値・キー・説明)を列に持つ表を作れば、テンプレートとして十分に機能します。ゼロから作るより、tblsで既存DBから出力したxlsxやMarkdownを雛形にするほうが早く確実です。項目が足りなければ、生成した表に列を足して運用します。
テーブル定義書とデータベース設計書は同じものですか?
データベース設計書は、テーブル定義書を含む上位の文書群を指すことが多い呼び方です。ER図、テーブル定義書、インデックス定義、CRUD図、コード値の一覧などをまとめて「データベース設計書」と呼びます。テーブル定義書はその中の、テーブルごとの列の詳細を書いた部分です。現場によっては両者を同じ意味で使うので、文書一覧で範囲を確かめてください。
論理名は日本語で書いてもよいですか?
論理名は日本語で書くのが一般的です。業務担当者が読む名前なので、画面の項目名や帳票の見出しと同じ言葉にそろえます。物理名は英小文字とアンダースコアで書き、日本語のテーブル名やカラム名は避ける方針です。PostgreSQLやMySQLのコメントは日本語を格納できるため、論理名をCOMMENT ONで持たせる方式とも両立します。
Excelのテーブル定義書からDDLを作ることはできますか?
できます。定義書の列を読んでCREATE TABLE文を組み立てるマクロやスクリプトは、多くの現場で作られています。ただし、この向きで運用すると正本がExcelになり、DDLを直接変えた改修が定義書に戻りません。DDL生成は初回の構築だけに使い、以降はDDLを正本にして定義書を生成する向きに切り替えることを勧めます。
テーブル定義書にインデックスやトリガーまで書くべきですか?
インデックスは書くべきです。性能の問題を調べるときに最初に見る情報で、手書きでは最も漏れやすい項目でもあります。トリガーやビューも、データを変える処理が隠れる場所なので一覧への記載対象です。tblsは、インデックス・制約・トリガーをテーブルごとの出力に含めます。手書きで全部を追うのが負担なら、それが自動生成に切り替える理由になります。
関連記事
- ER図とは?記号・線の読み方と書き方の手順、IE記法・IPA試験の表記とSQLへの落とし方:定義書の前提になるテーブル間の関係の書き方
- CRUD図の書き方:ER図と機能一覧から作る手順・SQLからの自動抽出・影響調査での使い方:定義書を変えるときの影響範囲の調べ方
- データベースの属性とは?カラム・フィールド・項目の違いと種類・制約をSQL例で解説:定義書のカラムに書く型と制約の選び方
- 基本設計とは?どこまで決めるか・成果物一覧と要件定義・詳細設計との違い:定義書を作る設計工程の全体像
- 仕様書とは?種類と書き方・記載項目テンプレート、設計書・要件定義書との違い:設計書全般の種類と書き分け