migrating-supabase

Supabase Migration Skill

対象プロジェクトにおけるSupabaseマイグレーションの作成・実行・修正ガイド。

Quick Start

新テーブル作成

cd supabase
# ファイル名は必ず現在時刻の時分秒まで含める
touch supabase/migrations/$(date +%Y%m%d%H%M%S)_add_table_name.sql

テーブル作成テンプレートに従い、以下を必ず全て記述:

1. CREATE TABLE
2. インデックス作成（RLSで使うカラム）
3. RLS有効化
4. authenticatedユーザー用ポリシー
5. service_role用ポリシー
6. GRANT ALL TO service_role

既存テーブルの変更

touch supabase/migrations/$(date +%Y%m%d%H%M%S)_alter_table_name.sql

→ カラム追加・変更 セクション参照

ローカルでテスト

# 実際のコマンドは .stdd.config.yml に従う
<commands.db_reset>   # マイグレーション再実行（DBリセット）
<commands.db_types>   # 型定義を再生成（全 apps[] 分）

主要コマンド

実際のコマンドは .stdd.config.yml の commands.* に従う。

用途	config キー
DBリセット（migration + seed再実行）	commands.db_reset
TypeScript型定義生成（全 apps[] 分）	commands.db_types

ローカル環境の起動・停止やフルセットアップ（起動 + 型生成）など、上記以外のプロジェクト固有コマンドは各プロジェクトの npm scripts 等を参照すること。

ファイル命名規則

時分秒まで含める（000000はファイル名衝突の原因になる）:

20251225103045_add_user_preferences.sql   -- OK
20251225000000_add_user_preferences.sql   -- NG: 衝突する

プレフィックス:

• add_: テーブル・カラム追加
• update_: カラム変更・型変更
• alter_: テーブル構造変更
• create_: インデックス・関数作成
• fix_: RLSポリシー修正・バグ修正
• drop_: 削除操作

新テーブル作成チェックリスト

□ 1. CREATE TABLE（id, user_id, created_at, updated_at, deleted_at を検討）
□ 2. RLSで使うカラムにインデックス作成
□ 3. ENABLE ROW LEVEL SECURITY
□ 4. authenticatedユーザー用RLSポリシー作成
□ 5. service_role用RLSポリシー作成
□ 6. GRANT ALL ON ... TO service_role（忘れると403エラー）
□ 7. `commands.db_reset`（.stdd.config.yml）でエラーなし
□ 8. `commands.db_types`（.stdd.config.yml）で型が生成される

詳細は テーブル作成テンプレート を参照。

カラム追加・変更（ALTER TABLE）

プロジェクトで頻出する変更パターン:

カラム追加

-- NULL許容のカラム追加（既存データに影響なし）
ALTER TABLE public.table_name ADD COLUMN new_column TEXT;

-- NOT NULLカラムの追加（既存行にはデフォルト値が入る）
ALTER TABLE public.table_name ADD COLUMN new_column TEXT DEFAULT '' NOT NULL;

カラム名変更

ALTER TABLE public.table_name RENAME COLUMN old_name TO new_name;