supabase-schema-from-requirements

要件からSupabaseスキーマを作成する

概要

ビジネス要件を、Supabase内で本番環境に対応したPostgresスキーマへ変換します。仕様策定からマイグレーションの適用までの全工程を対象とし、エンティティの抽出、適切な型と制約を備えたテーブル、Row Level Securityポリシー、パフォーマンスインデックス、タイムスタンプトリガー、TypeScript型の生成を行います。これを早い段階で適切に行うことが重要です。後続のすべての機能（認証、ストレージ、リアルタイム、エッジ関数）は、適切に設計されたテーブルに依存するためです。

前提条件

• Supabase CLIがインストールされ、プロジェクトにリンクされていること（npm install -g supabase、supabase link）
• プロジェクトに@supabase/supabase-js v2+がインストールされていること
• エンティティとアクセスルールを特定したビジネス要件、PRD、または仕様書
• ローカルのSupabaseが起動している（supabase start）か、リンク済みのリモートプロジェクトがあること

手順

ステップ1：要件を解析してマイグレーションを作成する

要件書を読み、エンティティ、属性、リレーションシップ、アクセス制御ルールを抽出します。各エンティティをPostgresのテーブルに対応付けます。

エンティティ抽出の例（プロジェクト管理アプリ）：

エンティティ	主なカラム	リレーションシップ
組織	name、slug、plan	複数のプロジェクトと複数のメンバーを持つ
プロジェクト	name、description、status	組織に属し、複数のタスクを持つ
タスク	title、priority、status、due_date	プロジェクトに属し、ユーザーに割り当てられる
メンバー	role（owner/admin/member）	ユーザーと組織をつなぐ中間テーブル

マイグレーションファイルを作成します。

npx supabase migration new create_tables
# Creates: supabase/migrations/TIMESTAMP_create_tables.sql

標準的なPostgresデータ型（uuid、text、integer、boolean、timestamptz、jsonb）を使用して、マイグレーションSQLを記述します。 完全なマイグレーション例（プロジェクト管理アプリ：テーブル、外部キー、インデックス、moddatetimeトリガー）については、references/worked-schema-examples.mdを参照してください。

データ型の選択ガイド：

用途	型	備考
主キー	uuid	常にuuid_generate_v4()をデフォルト値に設定します
名前、タイトル	text	Postgresではvarcharよりもこちらを推奨します
件数、順位	integer	シーケンスにはbigintを使用します
フラグ	boolean	デフォルト値にtrueまたはfalseを明示的に設定します
タイムスタンプ	timestamptz	タイムゾーンなしのtimestampは使用しないでください
柔軟なデータ	jsonb	クエリ可能なJSONです。設定やメタデータに使用します
リスト	text[]	シンプルなタグやラベルにはPostgresの配列を使用します

ステップ2：Row Level Securityポリシーを追加する

クライアントに公開するすべてのテーブルでRLSを有効にする必要があります。まず再利用可能なsecurity definerヘルパー関数を記述し、次にそれらを呼び出すテーブルごとのポリシーを記述します。1つのテーブルに対するひな形は次のとおりです。

alter table public.organizations enable row level security;

create policy "Users read own orgs"
  on public.organizations for select
  using (public.is_org_member(id));

完全なポリシー一式（is_org_member／is_org_adminヘルパー関数と、組織、メンバー、プロジェクト、タスクに対するすべてのselect／insert／update／deleteポリシー）については、references/rls-policies.mdを参照してください。ポリシー名は、対象者とアクションが分かるようにします（"Admins manage members"、"Assignee updates tasks"）。

ステップ3：マイグレーションを適用して型を生成する

# Apply migration locally
npx supabase db reset

# Or push to a linked remote project
npx supabase db push

# Generate TypeScript types from the live schema
npx supabase gen types typescript --local > types/supabase.ts

生成されたDatabase型をcreateClientのジェネリック型パラメーターとして渡し（import type { Database } from './types/supabase'を参照）、すべてのクエリでエンドツーエンドの型安全性を確保します。型付きの挿入、外部キー結合、複数テーブルのネストされた結合、RLSの適用確認を含む、型付きクライアントの完全な手順については、references/typescript-client.mdを参照してください。

出力

• すべてのテーブル、制約、インデックスを含む、supabase/migrations/配下のSQLマイグレーションファイル
• 要件のアクセス制御ルールに対応するRLSポリシー
• 再利用可能な認可チェック用のヘルパー関数（is_org_member、is_org_admin）
• updated_atを自動管理するmoddatetimeトリガー
• 型安全なクライアントクエリのためにtypes/supabase.tsに生成されたTypeScript型
• 頻繁に絞り込みに使われるカラム（status、due_date）に対する部分インデックス

エラー処理

エラー	原因	解決策
42P07: relation already exists	マイグレーションでテーブル名が衝突しています	create table if not exists を使用するか、テーブル名を変更します
23503: foreign key violation	存在しない親行を参照して挿入しています	先に親行を挿入するか、UUID を確認します
42501: insufficient privilege	RLS ヘルパー関数の権限が不足しています	関数定義に security definer を追加します
42883: function uuid_generate_v4() does not exist	拡張機能が有効になっていません	create extension if not exists "uuid-ossp" を追加します
supabase db push は成功するものの、テーブルが見つかりません	マイグレーションがすでに記録されています	supabase_migrations.schema_migrations を確認して修復します
PGRST204: column not found	TypeScript の型が同期されていません	npx supabase gen types typescript --local > types/supabase.ts を再実行します
new row violates row-level security	RLS ポリシーによって操作がブロックされています	auth.uid() が想定値と一致していることを確認し、ポリシーの using 句を確認します
moddatetime トリガーが失敗します	拡張機能が有効になっていません	マイグレーションの先頭に create extension if not exists "moddatetime" を追加します

例

E コマースのスキーマ（異なるドメインですが、パターンは同じです）。ストア、商品、注文、外部キーとインデックスを含む order_items の完全な E コマースマイグレーション SQL は、references/worked-schema-examples.md にあります。対応する型付きクライアントクエリは、references/typescript-client.md にあります。

リソース

• 行レベルセキュリティガイド
• データベースマイグレーション
• Supabase CLI リファレンス
• JavaScript クライアント — Select
• TypeScript サポート
• PostgreSQL データ型

次のステップ

このスキーマに認証の統合、ファイルストレージ、リアルタイムサブスクリプションを追加する場合は、supabase-auth-storage-realtime-core に進んでください。