2026-07 に実施した DDL(データベーススキーマ)レビューの結果と、そこから派生した実装・検証内容のまとめです。
GitLab の Issue/MR が正式な記録ですが、量が多いのでここに要約と「なぜそう決めたか」を集約しています。
| # | 内容 | 状態 | リンク |
|---|---|---|---|
| #1 | org_id 外部キー(FK)が無かった箇所に追加 | 対応済み | Issue #1 |
| #2 | UNIQUE制約(activated_key が未設定だった) |
対応済み | Issue #2 |
| #3 | monitor_alerts の複合インデックス追加 |
対応済み | Issue #3 |
| #4 / #10 | 日付TEXTカラムを TIMESTAMPTZ / DATE に変換(全64カラム) | 対応済み | #4 / #10 |
| #5 | profiles.roles(JSONB) の正規化版 profile_roles テーブルを追加 |
対応済み | Issue #5 |
| #6 | 組織の位置情報を PostGIS(location_point)で持てるように準備 |
対応済み | Issue #6 |
| #7 | SERIAL → GENERATED BY DEFAULT AS IDENTITY | 見送り | Issue #7 |
| #8 | (副産物)空DBからの prisma migrate deploy が失敗する不具合 |
対応済み | Issue #8 |
開発者との認識合わせで確定した点。ここが一番ズレやすいので重点的に記録しています。
roles を enum にする？ profile_roles テーブルにする？
profile_roles テーブル(自由文字列)。「組織ごとにカスタムロールがあり得る」と確認したため、固定 enum ではなく自由記述の role_name を持つ正規化テーブルにしました。profiles.roles(JSONB)は認可判定の正としてそのまま残し、新テーブルは検索用のミラーです。約25箇所ある権限チェックのコードは今回一切変更していません。
location を POINT にする？ PostGIS にする？
PostGIS(geography(Point, 4326))。「近い将来 距離検索/地図機能を作る予定がある」と確認したため、地球の曲率を考慮できる geography 型を採用。既存の location(JSONB)はそのまま、新カラムは追加のみで現状データは空(バックフィル対象データ無し)。
TIMESTAMPTZ 化はどこまでやる？
まず monitor_alerts.created_at だけでパイロットを実施し、安全性を確認 → その後「全テーブル一気に進めてほしい」との指示で残り64カラムも一括対応。prisma migrate diff は型変更時に DROP+ADD を生成し既存データを消してしまうため、全マイグレーションは手書き(ALTER COLUMN ... USING ...)にしています。
SERIAL → IDENTITY は？
見送り(wontfix)。Prisma は @default(autoincrement()) で常に SERIAL を出力し、IDENTITY にするには生成済みマイグレーションの手動編集が必要になり、次回の migrate dev と衝突し続ける。実質的な挙動差もほぼ無いため実施しない判断。
DBスキーマ変更のたびに、以下を毎回実施しています。次に何か触るときも同じ手順で。
ALTER COLUMN ... USING に置き換えるdev スキーマの実データで違反(孤児データ、キャスト不可な値)が無いか確認するdev スキーマに実際に適用(本番は触らない)、PostgREST のスキーマキャッシュを NOTIFY pgrst, 'reload schema' でリロードpytest app/tests/)を実行し、169件が通ることを確認migrate deployフルリプレイ+差分ゼロ確認)でのみ保証しています。今後スキーマを大きく触る際は同じ確認を推奨します。profile_roles は追加のみで、既存の約25箇所の権限チェックコードは profiles.roles(JSONB)を読んだままです。将来的にこちらへの移行を検討する場合は、認可ロジックなので別途慎重なレビューが必要です。location_point(PostGIS)は器だけ用意した状態で、実際に距離検索/地図機能を作る際に初めて使われます。2026-07-26
初版作成。DDLレビュー(#1〜#10、親Issue #9)が全項目解決したタイミングでまとめを作成。