テーブル定義書のテンプレートと書き方・サンプル

テーブル定義書とは

テーブル定義書に書く項目

各列について、最低限この属性を埋めると実装・レビューに耐える定義書になります。

論理名

人間向けの名前（例：メールアドレス）。画面ラベルや仕様の会話で使う。

物理名

DB 上の実カラム名（例：email）。スネークケースが一般的。

データ型

uuid / varchar(n) / integer / numeric(p,s) / boolean / timestamptz など。桁・精度も明記。

主キー（PK）

行を一意に識別する列。uuid + gen_random_uuid() か、連番（identity）が定番。

NOT NULL

必須かどうか。必須なら NOT NULL を付ける。

既定値

未指定時に入る値（例：now()、'member'、gen_random_uuid()）。

ユニーク / FK / インデックス

重複禁止（UNIQUE）、他テーブル参照（FOREIGN KEY）、検索高速化（INDEX）を必要に応じて付与。

説明

その列の意味・制約・想定値。レビューと将来の保守のために残す。

コピーして使えるテンプレート（Markdown サンプル）

下の表をコピーして、自分のテーブルに書き換えてください（users テーブルのサンプル）。Markdown なので GitHub / Notion / Issue にそのまま貼れます。Excel で管理したい場合は、手で同じ列を作ってもいいですが、d-bye ならDB設計から自動でExcelのテーブル定義書を無料生成できます（後述）。

| 論理名 | 物理名 | データ型 | 主キー | NOT NULL | 既定値 | 説明 |
|--------|--------|----------|:------:|:--------:|--------|------|
| ID | id | uuid | ○ | ○ | gen_random_uuid() | 主キー |
| メールアドレス | email | varchar(255) |  | ○ |  | ログインID（ユニーク） |
| 氏名 | name | varchar(100) |  | ○ |  | 表示名 |
| 役割 | role | varchar(20) |  | ○ | 'member' | 権限ロール |
| 作成日時 | created_at | timestamptz |  | ○ | now() | 登録日時 |
| 更新日時 | updated_at | timestamptz |  | ○ | now() | 更新日時 |

テーブル定義書の書き方（手順）

1. テーブルの目的を1行で書く（例：ユーザー＝ログインと権限管理）。
2. 主キーを決める（uuid + gen_random_uuid() か連番）。
3. 必要な列を洗い出し、論理名・物理名・データ型を埋める。
4. 各列の NOT NULL・既定値・桁/精度を決める。
5. ユニーク制約・外部キー（FK）・インデックスを付ける。
6. 説明欄に意味と制約を書き、レビューを受ける。
7. 確定したら CREATE TABLE に落とす（d-bye なら自動生成）。

d-bye なら：書いた定義から Excel設計書とDDLが無料で出る

d-bye は「設計書を起点」として、テーブル・列・制約・FK をビジュアルに定義します。上のひな形（users）と同じ内容を作ると、次の PostgreSQL DDL と Excel のテーブル定義書(.xlsx)が、サインアップ不要・無料でそのままダウンロードできます。

CREATE TABLE users (
  id          uuid         PRIMARY KEY DEFAULT gen_random_uuid(),
  email       varchar(255) NOT NULL UNIQUE,
  name        varchar(100) NOT NULL,
  role        varchar(20)  NOT NULL DEFAULT 'member',
  created_at  timestamptz  NOT NULL DEFAULT now(),
  updated_at  timestamptz  NOT NULL DEFAULT now()
);

• ✓DDL（PostgreSQL / SQLite 切替）と Excel のテーブル定義書(.xlsx)は無料。会員登録もクレジットカードも不要。
• ✓CRUD画面（React/TypeScript）とAPI（Rust または Node.js）まで欲しい場合は、有料プランでZIP一括エクスポート。
• ✓型検証＋コンパイルチェックを通すので、壊れたコードを出さない。
• ✓定義を直すと設計書が起点のまま、再生成で全体が追従（Excelの二重管理が消える）。

よくある質問

テーブル定義書に最低限書くべき項目は？

論理名・物理名・データ型・主キー・NOT NULL・既定値・説明の7項目です。加えてユニーク制約・外部キー（FK）・インデックス・桁/精度を書けると、そのまま実装に落とせます。

テーブル定義書を自動で作成できるツールはありますか？

はい。d-bye のDBビルダーでテーブル・列・関連をGUIで設計すると、Excelのテーブル定義書(.xlsx)とPostgreSQL/SQLite向けDDLを無料・サインアップ不要でダウンロードできます。詳しい使い方は「テーブル定義書 作成ツール」ページで解説しています。

Excel とどちらがいいですか？

チームの慣習に合わせて構いません。Excel は配布が容易、Markdown はレビュー（差分）と相性が良いです。d-bye はさらに進んで「定義書＝動くコードの素」にし、書いた内容からExcel設計書・DDL・画面を生成するため、定義書とコードの二重管理がなくなります。

テーブル定義書から CREATE TABLE は自動で作れますか？

d-bye ではビジュアルに作った DB 設計から PostgreSQL / SQLite の DDL を無料で自動生成できます。CRUD 画面とAPIも一括で出力したい場合は有料プランが必要です。Excel だけの運用では手書きになります。

ER図との違いは？

ER図はテーブル間の「関係（リレーション）」を俯瞰する図、テーブル定義書は1テーブルの「列と制約」を厳密に決める表です。役割が違うので両方そろえるのが理想です。