当サイトの記事は編集部が国土交通省・IPA・デジタル庁などの公的機関の情報、規格や業界団体の公開情報を調べて独自に執筆しています。記事内にIT・Webエンジニアの転職サービスへの案内（広告）を含みます。
データベースの設計を任されて、『テーブル定義書を作っておいて』と言われた。ひな形を開いてみたら、PKやFKなど見慣れない欄が並んでいて戸惑っている。そんな方も多いはずです。
結論から言うと、テーブル定義書は項目1行ごとに「名前」「型と長さ」「必須か」「意味と例」の4点を埋めれば、読む人が迷わない文書になります。キーや索引の欄は、その4点が書けてから足していけば大丈夫です。
この記事を読めば、テーブル定義書の書き方と、データベース設計書全体のまとめ方が分かります。
テーブル定義書とは？データベース設計書との関係
テーブル定義書は、データベースのテーブル1つごとに、どんな項目をどんな形で持つかを書いた文書です。データベース設計書という大きなまとまりの中の、中心になる1冊と考えると分かりやすいですよ。
システムが扱うデータは、データベースの中で表の形をしたテーブルに入っています。テーブル定義書は、その表の列（項目）を1つずつ説明した設計図です。
データベース設計書と呼ばれる物は、テーブル定義書だけでなく、いくつかの文書をまとめた呼び名として使われることが多いです。
| 文書 | 書く中身 | 読む人が知りたいこと |
|---|---|---|
| テーブル一覧 | テーブル名と、何を入れるテーブルか | どんなデータを持っているか |
| テーブルの関係図 | テーブルどうしのつながり | どのデータとどのデータがつながるか |
| テーブル定義書 | テーブルごとの項目、型、必須、キー | 項目の形と意味 |
| コード定義 | 区分やステータスの値と意味 | 数字や記号が何を表すか |
デジタル庁のDS-100では、要件定義書の機能要件として「データ」に関する事項を定めるとしています。要件定義で決めたデータを、実際の表の形に落とすのがデータベース設計書の役目なんです。
設計書の種類全体の中での位置づけは、基本設計書とは？や詳細設計書とは？でも紹介しています。
項目1行は4点で書く
テーブル定義書の1行は「名前」「型と長さ」「必須か」「意味と例」の4点が基本です。特に「意味と例」を空欄にしないことが、使われる定義書かどうかの分かれ目になります。
テーブル定義書でありがちなのが、項目名と型だけが並んでいて、何が入るのか分からないパターンです。『この status って何が入るの？』と、結局作った人に聞きに行くことになるんですよね。
そこで編集部では、1行を4点で書く記入表を作ってみました。
| 書く点 | 書く中身 | 抜けると起きること |
|---|---|---|
| 名前 | 項目の物理名（英字）と論理名（日本語） | 画面やAPIの項目と対応が取れない |
| 型と長さ | 文字・数値・日付などの型と、桁数 | 入らない値が来て登録に失敗する |
| 必須か | 空のままを許すか、初期値は何か | 空の時の扱いが人によって違う |
| 意味と例 | 何を入れる項目か、入る値の例 | 項目を読み違えて誤ったデータが入る |
記入例：備品テーブル
社内の備品貸出システムの「備品」テーブルを例にします。どれも編集部の架空の記入例です。
| 物理名 | 論理名 | 型と長さ | 必須 | キー | 意味と例 |
|---|---|---|---|---|---|
| item_id | 備品ID | 文字・最大10桁 | 必須 | PK | 備品ごとに付ける番号。例 A0123 |
| item_name | 備品名 | 文字・最大50桁 | 必須 | 社内で呼んでいる名前。例 会議用プロジェクター | |
| place_cd | 置き場所コード | 文字・最大3桁 | 必須 | FK | 置き場所テーブルのコード。例 F03 |
| status | 状態 | 数値・1桁 | 必須 | 貸出の状態。コード定義の「備品状態」を見る | |
| note | 備考 | 文字・最大200桁 | 任意 | 自由に書くメモ。空でもよい |
桁数は、画面設計書の入力のルールやAPI仕様書の項目と合わせておくのがポイントです。画面と食い違うと、画面では入力できるのに保存で失敗する、ということが起きてしまいます。
テーブル定義書のテンプレートと書く順番
テーブル定義書のテンプレートは「表紙と変更の記録」「テーブル一覧」「テーブルごとのシート」「コード定義」の4つで作ると、使い回しやすくなります。Excelなら1テーブル1シートの形が一般的です。
データベース設計書を書く時は、いきなり1テーブルずつ細かく書き始めないのがコツです。先に全体を並べてから、1つずつ埋めていきましょう。
- 要件定義書から、システムが扱うデータを書き出す
- データのまとまりごとにテーブルを分け、テーブル一覧を作る
- テーブルどうしのつながりを関係図にする
- テーブルごとに、項目1行を4点で書く
- 区分や状態の値をコード定義にまとめる
- 画面設計書やAPI仕様書の項目と照らし合わせる
テンプレートに入れておく項目
| シート | 入れる項目 | 書き方のコツ |
|---|---|---|
| 表紙と変更の記録 | システム名、版、日付、変えた所 | 項目を足した・型を変えた時は毎回残す |
| テーブル一覧 | 物理名、論理名、概要、主に使う画面 | 一覧から各シートへ飛べるようにする |
| テーブルごとのシート | 項目1行ずつの4点、キー、索引 | 列の並びは全シートでそろえる |
| コード定義 | コードの種類、値、意味、使うテーブル | 「その他」の値の扱いも書く |
データベース仕様書を書き方の決まったひな形で作っておくと、担当が変わっても形がそろいます。Excelで作るか、Markdownで作るかの考え方は、設計書のテンプレート・サンプルで比べています。
キーと索引の欄の書き方
PKは主キーのことで、そのテーブルで1行を見分けるための項目です。FKは外部キーで、ほかのテーブルの主キーを指している項目を表します。
| 欄 | 意味 | 書き方の例 |
|---|---|---|
| PK | 主キー。1行を見分ける項目 | 備品IDに「PK」 |
| FK | 外部キー。ほかのテーブルを指す項目 | 置き場所コードに「FK（置き場所テーブル）」 |
| 索引 | 検索を速くするための目印 | よく検索に使う項目に付ける |
| 一意 | 同じ値を2回入れられない項目 | 社員番号など |
FKの欄には、どのテーブルを指しているかまで書いておくと親切です。
テーブルの分け方に迷ったら
『1つのテーブルに全部入れたらだめなの？』と思う方もいますよね。実は、同じ内容が何度も出てくる項目は、別のテーブルに分けておくのが基本なんです。
例えば備品テーブルに置き場所の名前と住所をそのまま書くと、置き場所の名前が変わった時に全部の行を直すことになります。置き場所テーブルを分けてコードでつないでおけば、直すのは1か所で済みます。
| よくある迷い | 考え方の目安 |
|---|---|
| 同じ名前や住所が何行にも出てくる | 別のテーブルに分けてコードでつなぐ |
| 1人に複数の値がある（電話番号が複数など） | 値ごとに1行になる別のテーブルにする |
| 毎日増えていく記録（貸出の履歴など） | 台帳とは別に、記録用のテーブルにする |
分けたテーブルどうしのつながりは、関係図に線で書いておきましょう。
書く時に迷いやすい所
迷いやすいのは「名前の付け方」「空の値の扱い」「コード値の意味」の3つです。どれも、決めたことを定義書の最初のページにまとめておくと、全テーブルで迷わなくなります。
『名前は英語？ローマ字？』『空のままでいいの？』と、細かい所で手が止まることってありますよね。こうした決めごとは、テーブルごとではなく全体のルールとして先に決めてしまいましょう。
- 物理名の付け方（英語かローマ字か、区切りの記号）
- 日付や金額の型と、桁数の考え方
- 空の値を許す項目の決め方
- 登録日や更新者など、全テーブルに付ける項目
- コード値を数字にするか文字にするか
コード値は「値と意味の表」にする
状態や区分を数字で持つ時は、値の意味を表にしておきます。1が何で2が何かが分からないと、データを読む人が毎回ソースを探すことになるんです。
| 値 | 意味 | 使う場面 |
|---|---|---|
| 0 | 貸出できる | 備品が棚にある時 |
| 1 | 貸出中 | 申し込みが承認された時 |
| 9 | 使えない | 故障や廃棄の時 |
データベースを直接直して項目を足したのに、テーブル定義書を直し忘れることがよくあります。直したらその日のうちに定義書も直し、変更の記録に残しておきましょう。
テーブル定義書でよくある相談
よく見かけるのは「定義書の欄の意味が分からない」「書き方の見本がほしい」「コード値の意味を書いてもらうには」の3つです。どれも、欄の意味と4点の基本を押さえれば答えが見えてきます。
よく見かける相談を、内容をまとめた形で紹介します。
相談1：PKやFKなど、定義書の欄の意味が分からない
テーブル定義書に並んでいる「区」「PK」「FK」「AK」などの欄の意味を知りたい、という相談です。閲覧数がとても多く、同じところでつまずく方がたくさんいることが分かります。
PKとFKは、先ほどの表のとおり主キーと外部キーです。そのほかの略称は会社のひな形ごとに意味が違うことがあるので、ひな形を作った人か、定義書の最初のページの説明で確かめてみてください。
相談2：データベース設計書の書き方の見本がほしい
勤怠管理のシステムを作ろうとしていて、データベース設計書の書き方を詳しく知りたい、という相談も多く見かけます。
まずは扱うデータを書き出し、テーブル一覧を作るところから始めてみてください。そのうえで、この記事の4点の記入表に沿って1テーブルずつ埋めていけば、形の整った設計書になります。
例えば勤怠管理なら、社員の台帳、毎日の出退勤の記録、休暇の申請、のように分けて考えてみてください。台帳と、毎日増える記録を別のテーブルにするだけで、ぐっと見通しがよくなりますよ。
相談3：コード値の意味を書いてほしいと頼むには？
テーブル定義書にコード値の意味を書いてほしいと、作った会社に頼みたい。どう書けば伝わるか、という相談です。
「状態の項目の値ごとに、意味と使う場面を表にしてほしい」と、ほしい表の形を見せて頼むのが一番伝わります。上のコード値の表のような見本を添えると、相手も迷いません。
データベース設計の経験を仕事に活かす
データの形を決める仕事は、システム全体の土台を決める仕事です。テーブル定義書を書ける人は、基本設計や詳細設計を任される場面で頼りにされます。
今の職場で設計の担当を少しずつ広げていくのも、立派な道です。そのうえで、要件定義や設計を任される職場に進みたい方は、求人の仕事内容を比べてみると道が見えてきますよ。
IT・Webエンジニアの転職（PR）
仕様書を書く経験を活かせる職場を探すなら、求人も比べてみる
要件定義や設計を任されるか、発注側か開発側か、扱うシステムや働き方は会社によって大きく違います。担当したい工程や条件から、IT・Webエンジニアの求人を比べてみてください。
無料ITエンジニアの求人を探す求人の条件・待遇は各求人票と応募先の案内でご確認ください。
APIで受け渡す項目との合わせ方はAPI仕様書の書き方、仕様書全体の位置づけは仕様書とは？で確かめられます。
よくある質問
テーブル定義書には何を書けばいいですか？
テーブルごとに、項目1行ずつ「名前」「型と長さ」「必須か」「意味と例」の4点を書きます。そのうえで、主キーや外部キー、索引の欄を足していきます。
テーブル定義書とデータベース設計書は違う物ですか？
データベース設計書は、テーブル一覧やテーブルの関係図、テーブル定義書、コード定義などをまとめた呼び名として使われることが多いです。テーブル定義書はその中心になる文書です。
テーブル定義書のテンプレートはどう作ればいいですか？
表紙と変更の記録、テーブル一覧、テーブルごとのシート、コード定義の4つを用意すると使い回しやすくなります。項目の列の並びは全シートでそろえておきましょう。
テーブル定義書は誰が作りますか？
一般的には、データベースの設計を担当する開発側の技術者が作ります。発注側は、項目の意味や業務のルールが正しく書かれているかを確かめる役になることが多いです。
DBの仕様書はExcelで書くのが一般的ですか？
Excelで1テーブル1シートにする形はよく使われています。ただ、変更の履歴を残しやすいMarkdownなどの形で管理する現場もあるので、チームで使いやすい物を選びましょう。
まとめ
- テーブル定義書は、テーブルごとの項目の形と意味を書いた文書
- データベース設計書は、一覧・関係図・定義書・コード定義のまとまり
- 項目1行は名前・型と長さ・必須か・意味と例の4点で書く
- 名前の付け方や空の値の扱いは、全体のルールとして先に決める
- コード値は値と意味の表にし、直したら定義書もすぐ直す
コメント