db-enforcer

DB Enforcer

概要

TypeScript アプリケーション層と PostgreSQL 永続化層の間で、データの整合性とアーキテクチャの一貫性を確保します。CHECK 制約が TypeScript の型を反映していること、変更の適用前にマイグレーションが生成されていること、すべてのテーブルが Row-Level Security によって保護されていることを確認し、型のずれを防ぎます。

使用するタイミング： スキーマ設計、マイグレーション計画、RLS ポリシーの作成、Prisma モデルのマッピング、制約の監査、ダウンタイムなしのデプロイ。

使用しないタイミング： アプリケーション層のビジネスロジック、フロントエンドの状態管理、PostgreSQL 以外のデータベース。RLS の完全な監査、パフォーマンスチューニング、コンプライアンス検証には、代わりに database-security スキルを使用してください。

クイックリファレンス

パターン	API/ツール	主なポイント
型と DB の同期	prisma migrate dev --create-only	変更を適用する前に SQL を生成します
命名の統一	@map / @@map	SQL では snake_case、TS では camelCase
主キー	DEFAULT uuidv7()	シーケンシャルでグローバルに一意、高速なインデックス作成（PG 18 以降）
仮想列	GENERATED ALWAYS AS (...) VIRTUAL	ディスクコストゼロ、読み取り時に計算（PG 18 以降）
時間的な一意性	EXCLUDE USING gist	範囲の重複をネイティブに防止
NOT VALID 制約	ADD CONSTRAINT ... NOT VALID	テーブルロックなしで制約を追加
TypedSQL	prisma.$queryRawTyped()	.sql ファイルを介した型安全な生 SQL
リレーションのエミュレーション	relationMode = "prisma"	FK がない環境で整合性を確保（4.8.0 以降 GA）
論理削除	Prisma $extends	クライアント拡張による横断的な関心事
RLS 標準	(select auth.uid()) = user_id	initPlan キャッシュを使用する、デフォルトの自分のデータへのアクセス ポリシー
チーム RLS	EXISTS サブクエリ	結合テーブルを介した権限チェック
列レベルのセキュリティ	PostgreSQL Views	公開 API から機密列を隠します

同期プロトコル

スキーマを変更する場合は、必ず次の手順に従ってください。

1. 型と DB の照合：TS に enum または union を追加する場合、SQL の対応する CHECK 制約を確認します
2. マイグレーションを先に生成：適用する前に、prisma migrate dev --create-only を使用して SQL マイグレーションを生成します
3. 命名の統一：明示的な @map／@@map ディレクティブを使い、SQL では snake_case、TS では camelCase を徹底します
4. 整合性の監査：prisma validate を実行し、リレーションのスカラーにインデックスが不足していないか確認します
5. RLS の検証：新しいテーブルすべてで RLS が有効になっており、適切なポリシーが設定されていることを確認します
6. ロックの評価：マイグレーションで CREATE INDEX CONCURRENTLY または NOT VALID パターンが必要かどうかを評価します

PostgreSQL のバージョン要件

このスキルのいくつかのパターンには、特定の PostgreSQL バージョンが必要です。

機能	最小バージョン	代替手段
uuidv7()	PostgreSQL 18	pgcrypto を介した gen_random_uuid()（UUIDv4）
仮想列	PostgreSQL 18	STORED 生成列（PG 12 以降）
EXCLUDE USING	PostgreSQL 9.0	アプリケーション層での重複チェック
NOT VALID	PostgreSQL 9.1	ダウンタイム中に制約の追加をスケジュールする
security_invoker	PostgreSQL 15	権限を制限した security_definer を使用する

よくある間違い

間違い	正しいパターン
マイグレーションを使わずに SQL の変更を手動で実行する	適用する前に prisma migrate dev --create-only で番号付きマイグレーションを生成する
URL に自動採番 ID や生の ID を使用する	グローバルに一意で、列挙できない識別子として UUIDv7 を使用する
enum や union に CHECK 制約を設定しない	TypeScript の型に対応する CHECK 制約をデータベースレベルで追加する
明示的なマッピングなしで snake_case と camelCase を混在させる	@map と @@map を使用して、SQL では snake_case、TypeScript では camelCase を徹底する
行レベルセキュリティポリシーのないテーブル	(select auth.uid()) = user_id をデフォルトとして、すべてのテーブルに RLS ポリシーを適用する
1 回のデプロイで列を DROP または RENAME する	拡張と縮小の手法を使う：新しい列を追加し、両方に書き込み、バックフィルし、読み取り先を切り替え、古い列を削除する
大きなテーブルにフルロックを伴う NOT NULL を追加する	まず NULL を許可する列を追加してバックフィルし、その後 NOT VALID を指定して NOT NULL を追加する
CONCURRENTLY を指定せずにインデックスを作成する	テーブルロックを避けるため、生 SQL のマイグレーションで CREATE INDEX CONCURRENTLY を使用する
RLS で auth.uid() をサブセレクトなしで直接使用する	initPlan キャッシュを有効にするため、(select auth.uid()) で囲む
すべての PG バージョンで uuidv7() が使えると思い込む	PostgreSQL 18 以降であることを確認し、古いバージョンでは gen_random_uuid() にフォールバックする

命名規則

Prisma モデルでは TypeScript に camelCase を使用し、PostgreSQL では snake_case にマッピングする必要があります。

レイヤー	規則	適用方法
TypeScript	camelCase	Prisma モデルのフィールド名
PostgreSQL	snake_case	@map / @@map
Enum	UPPER_SNAKE	CHECK 制約
インデックス	snake_case	idx_table_column

デプロイパイプライン

マイグレーションは厳密な順序で進めます。

1. prisma migrate dev --create-only -- SQL をローカルで生成して確認する
2. prisma validate -- スキーマの整合性を検証する
3. ステージング／プレビュー用データベースに適用し、統合テストを実行する
4. prisma migrate deploy -- CI/CD パイプラインで本番環境に適用する
5. ロック競合とクエリプランの性能低下を監視する

他のスキルとの関係

• database-security：RLS の完全な監査、PGAudit の設定、Supabase 固有のパターン、Convex の認証ガード、コンプライアンス検証を扱います。詳細なポリシーレビューとアクセスシミュレーションには database-security を使用してください。RLS を整合性ワークフローの一部として扱うスキーマ設計とマイグレーションパターンには db-enforcer を使用してください。

委任

• 既存スキーマに制約やインデックスの不足がないか監査する：Explore エージェントを使用します
• 本番データベース向けのゼロダウンタイム移行戦略を計画する：Plan エージェントを使用します
• 型の整合と RLS の設定を含む、スキーマ全体のリファクタリングを実行する：Task エージェントを使用します
• RLS ポリシーの回避経路とパフォーマンス上の問題をレビューする：database-security スキルを使用します

参考資料

• PostgreSQL の整合性パターン、UUIDv7、仮想列、時間的制約
• Prisma のアーキテクチャ、TypedSQL、拡張機能、エッジファーストパターン
• マイグレーションの安全性に関するプロトコル、破壊的変更、ロールバック戦略
• 行レベルセキュリティ、列レベルセキュリティ、監査ログ