database-patterns

データベースパターン — クイックリファレンス

厳守事項

ルール	使用するもの	使用しないもの
データ型	TEXT	VARCHAR
主キー	UUID	SERIAL、BIGINT
論理削除	deleted_at TIMESTAMP	DELETE FROM
外部キー	アプリケーション側での検証	REFERENCES、ON DELETE CASCADE
標準カラム	id、created_at、updated_at、deleted_at	いずれかを省略する

マイグレーションのテンプレート

テーブル、トリガー、論理削除用の部分インデックスを含む SQL マイグレーションです。

完全な SQL テンプレートについては、code-templates.md を参照してください。

公開するテーブルオブジェクト

UUIDTable を拡張し、varchar() ではなく text() を使い、標準のタイムスタンプカラムを追加します。

完全なテンプレートについては、code-templates.md を参照してください。

エンティティのデータクラス

Entity<Instant> を実装し、すべてのビジネスフィールドと createdAt、updatedAt、deletedAt を含めます。

完全なテンプレートについては、code-templates.md を参照してください。

リポジトリパターン

インターフェースと Default* の実装を用意します。読み取りには db.replica、書き込みには db.primary を使います。論理削除は deletedAt の更新で行います。convert() メソッドで ResultRow をエンティティにマッピングします。

インターフェースと実装のコード全体については、code-templates.md を参照してください。

新しいテーブルを作成する場合

完全なチェックリスト：

1. SQL マイグレーションファイル（連番の次の番号）
2. module-repository/table/ 内のテーブルオブジェクト
3. module-repository/entity/ 内のエンティティデータクラス
4. module-repository/constant/ 内の列挙型／定数（必要な場合）
5. リポジトリのインターフェースと実装
6. リポジトリ用ファクトリービーン
7. リポジトリのテスト

Flyway のルール

• デプロイ済みの連番にある欠番を埋めるマイグレーションは、絶対に追加しないでください
• デプロイ済みのマイグレーションファイルの名前は、絶対に変更しないでください
• マイグレーション番号は最新の番号から連番にしてください
• マイグレーションはシンプルに、対象を絞ってください（1つのマイグレーションにつき1つのテーブル）

注意点

• .value を使うのは id だけです。それ以外はそのまま使います。 row[Table.id].value は UUID を返しますが、row[Table.projectId] はすでに UUID を返します。id 以外のカラムに .value を追加するとコンパイルエラーになります。
• gen_random_uuid() と uuid_generate_v4() は、プロジェクトごとにどちらか一方を選んでください。 混在しても動作しますが、コードレビューが分かりにくくなります。既存のマイグレーションを確認し、プロジェクトでどちらを使っているか確認してください。
• SoftDeleteTable を拡張する場合、createdAt、updatedAt、deletedAt を再宣言しないでください。 これらは継承されます。再宣言するとカラムの重複エラーになります。
• インデックスで WHERE deleted_at IS NULL を付け忘れると、容量を無駄にします。 論理削除テーブル上のすべてのインデックスは、部分インデックスにしてください。通常のインデックスには、誰もクエリしない削除済みレコードも含まれます。
• JSON を格納するテキストカラムも、Exposed では text() を使ってください。 Postgres では JSONB、Kotlin では text() を使い、エンティティ層でシリアライズ／デシリアライズします。