| name | db-design |
| description | RDBMS + ORM 前提のデータベース・スキーマ設計ガイド（ツール非依存）。DB設計ワークフロー、テーブル設計原則、正規化/非正規化判断、型設計、インデックス戦略、リレーション設計、マイグレーション管理をカバー。テーブル設計、データモデル設計、マイグレーション時に使用。 |
データベース・スキーマ設計ガイド
RDBMS + ORM 前提のフレームワーク非依存ガイド。
DB 設計ワークフロー
1. 要件からエンティティを抽出
2. 関連（リレーション）を定義
3. 属性と制約を決定
4. 正規化 (3NF を目標)
5. 非正規化の検討（パフォーマンス要件に応じて）
6. インデックス設計
7. マイグレーション作成
テーブル設計の原則
命名規則
テーブル名: 複数形・スネークケース (users, order_items)
カラム名: スネークケース (created_at, user_id)
外部キー: {参照テーブル単数}_id (user_id, order_id)
真偽値: is_, has_, can_ プレフィックス (is_active, has_permission)
共通カラム
id : 主キー（UUID or 連番）
created_at : 作成日時（NOT NULL）
updated_at : 更新日時（NOT NULL）
deleted_at : 論理削除日時（NULL 許容、必要な場合のみ）
データ型選択の原則
| 用途 | 推奨 | 避ける |
|---|
| 主キー | UUID / ULID / auto increment | 文字列ID |
| 日時 | timestamp with timezone | 文字列 |
| 金額 | decimal / integer (最小単位) | float |
| 状態 | enum / varchar + CHECK | integer |
| フラグ | boolean | integer (0/1) |
| JSON | jsonb (対応DBの場合) | text |
正規化と非正規化
正規化 (3NF を基本目標)
| レベル | 排除するもの | 例 |
|---|
| 1NF | 繰り返しグループ | カンマ区切りの値 → 別テーブル |
| 2NF | 部分関数従属 | 複合キーの一部だけで決まる属性 |
| 3NF | 推移関数従属 | 非キー属性が別の非キー属性に依存 |
非正規化の判断基準
| 場面 | 手法 | トレードオフ |
|---|
| 読み取り頻度が高い集計値 | 事前計算カラム追加 | 更新時の整合性コスト |
| 頻繁な JOIN の回避 | 冗長カラム追加 | ストレージ + 更新コスト |
| 履歴データの保持 | スナップショット | ストレージ増 |
| 検索パフォーマンス | 非正規化ビュー | 同期コスト |
原則: まず正規化し、計測に基づいて非正規化を検討
詳細: references/normalization.md
型設計
Branded Types（ID の混同防止）
UserId と OrderId を型レベルで区別
→ 引数の取り違えをコンパイル時に検出
Enum / Union Types（状態表現）
Status = 'pending' | 'approved' | 'rejected'
設計原則:
- 状態遷移を明確に定義
- 無効な遷移を型レベルで防ぐ
- DB には文字列 or enum 型で保存
Nullable 設計
NOT NULL をデフォルトとし、NULL は明確な理由がある場合のみ使用
NULL の正当な用途:
- 任意フィールド（ユーザーが未入力）
- 論理削除の deleted_at
- 将来の拡張フィールド
NULL を避けるべき場面:
- デフォルト値で代替可能な場合
- 空文字列/0/false で表現できる場合
インデックス戦略
インデックスを付けるべきカラム
| 対象 | 理由 |
|---|
| 外部キー | JOIN パフォーマンス |
| WHERE で頻繁に使うカラム | 検索パフォーマンス |
| ORDER BY で使うカラム | ソートパフォーマンス |
| UNIQUE 制約のあるカラム | 一意性保証 |
インデックスの種類
| 種類 | 用途 |
|---|
| 単一カラム | 単純な条件検索 |
| 複合 | 複数条件の AND 検索（左端一致原則） |
| 部分 | 条件付きインデックス（WHERE 句付き） |
| 全文検索 | テキスト検索 |
避けるべきパターン
- 低カーディナリティのカラムへの単独インデックス
- 過剰なインデックス（書き込みパフォーマンス低下）
- 使われないインデックスの放置
詳細: references/indexing-strategy.md
リレーション設計
| 関係 | 実装 | 例 |
|---|
| 1:1 | 外部キー + UNIQUE 制約 | users ↔ profiles |
| 1:N | 子テーブルに外部キー | users → orders |
| N:M | 中間テーブル | users ↔ roles (user_roles) |
| 自己参照 | 同テーブルの外部キー | categories (parent_id) |
中間テーブルの設計
中間テーブル名: {テーブルA}_{テーブルB} (アルファベット順)
例: user_roles, order_items
カラム:
- 各テーブルの外部キー
- created_at
- 追加属性（関係に紐づくデータ）
カスケード設計
| アクション | 用途 | 注意 |
|---|
| CASCADE | 親削除時に子も削除 | 意図しない大量削除に注意 |
| SET NULL | 親削除時に NULL に | NULL 許容カラムのみ |
| RESTRICT | 子が存在する場合は親削除を拒否 | デフォルト推奨 |
マイグレーション管理の原則
- マイグレーションは常に前進（ロールバック用ではなく新規マイグレーションで修正）
- 破壊的変更は段階的に行う（カラム追加 → データ移行 → 旧カラム削除）
- 本番データに対する破壊的操作は慎重に（バックアップ必須）
- マイグレーションファイルはバージョン管理に含める
レビューチェックリスト
リファレンス
