5.2. データベース設計規則

5.2.1. テーブル命名規則

規則	例
小文字 + snake_case	user_profiles
複数形を使用	users, orders
接頭辞の禁止	tbl_users (X) → users (O)
予約語の使用禁止	user (X) → users (O)

5.2.2. カラム命名規則

規則	例
小文字 + snake_case	created_at, user_name
テーブル名接頭辞の禁止	user_user_name (X) → user_name (O)
Booleanカラム	is_ または has_ 接頭辞
日付/時刻カラム	_at 接尾辞

5.2.3. 必須カラム

すべてのテーブルに以下のカラムを含めなければなりません。

カラム	型	説明
id	BIGSERIAL または UUID	主キー
created_at	TIMESTAMP WITH TIME ZONE	作成日時
updated_at	TIMESTAMP WITH TIME ZONE	更新日時

CREATE TABLE users (
    id          BIGSERIAL PRIMARY KEY,
    name        VARCHAR(100) NOT NULL,
    email       VARCHAR(255) NOT NULL UNIQUE,
    is_active   BOOLEAN NOT NULL DEFAULT true,
    created_at  TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now(),
    updated_at  TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now()
);

5.2.4. 主キー戦略

戦略	型	使用基準
BIGSERIAL	自動増分整数	一般的なビジネスエンティティ（デフォルト）
UUID	uuid	分散環境、外部公開識別子

UUID使用時：

CREATE EXTENSION IF NOT EXISTS "pgcrypto";

CREATE TABLE documents (
    id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    title       VARCHAR(255) NOT NULL,
    created_at  TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now(),
    updated_at  TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now()
);

5.2.5. インデックス命名規則

idx_{テーブル名}_{カラム名}

種別	命名規則	例
通常インデックス	idx_{table}_{column}	idx_users_email
複合インデックス	idx_{table}_{col1}_{col2}	idx_orders_user_id_status
ユニークインデックス	uniq_{table}_{column}	uniq_users_email

CREATE INDEX idx_users_email ON users (email);
CREATE UNIQUE INDEX uniq_users_email ON users (email);
CREATE INDEX idx_orders_user_id_status ON orders (user_id, status);

5.2.6. 外部キー命名規則

fk_{テーブル名}_{参照テーブル名}

ALTER TABLE orders
    ADD CONSTRAINT fk_orders_users
    FOREIGN KEY (user_id) REFERENCES users (id);

5.2.7. 禁止事項

禁止項目	理由
複合主キー	JOIN複雑度の増加、jOOQコード生成の複雑化
TEXT型の乱用	長さ制限のないカラムは明示的に必要な場合のみ
FLOAT / DOUBLE	金融データの精度問題 → NUMERICを使用
予約語のテーブル/カラム名	SQL互換性の問題
トリガーベースのビジネスロジック	アプリケーションレイヤーで処理