Supabase Core Skill

すべての Supabase プロジェクトに共通するコアコンセプト、CLI ワークフロー、パターン。

Sources: Supabase Docs | Supabase CLI

---

Core Principle

ローカルファースト、マイグレーションをバージョン管理下に、本番環境に直接触れない。

Supabase CLI でローカルに開発し、すべての変更をマイグレーションとして記録し、CI/CD を通じてデプロイします。

---

Supabase Stack

Service	Purpose
Database	PostgreSQL with extensions
Auth	ユーザー認証、OAuth プロバイダー
Storage	RLS 付きファイルストレージ
Edge Functions	サーバーレス Deno 関数
Realtime	WebSocket サブスクリプション
Vector	AI 埋め込み (pgvector)

---

CLI セットアップ

インストール＆ログイン

# macOS
brew install supabase/tap/supabase

# npm (代替方法)
npm install -g supabase

# ログイン
supabase login

プロジェクト初期化

# プロジェクトディレクトリで
supabase init

# 作成される:
# supabase/
# ├── config.toml      # ローカル設定
# ├── seed.sql         # シードデータ
# └── migrations/      # SQL マイグレーション

リモートにリンク

# ダッシュボード URL からプロジェクト ref を取得: https://supabase.com/dashboard/project/<ref>
supabase link --project-ref <project-id>

# 既存スキーマを取得
supabase db pull

ローカルスタックを起動

supabase start

# 出力:
# API URL: http://localhost:54321
# GraphQL URL: http://localhost:54321/graphql/v1
# DB URL: postgresql://postgres:postgres@localhost:54322/postgres
# Studio URL: http://localhost:54323
# Anon key: eyJ...
# Service role key: eyJ...

---

マイグレーション ワークフロー

オプション 1: ダッシュボード + 差分生成 (クイックプロトタイピング)

# 1. ローカル Studio (localhost:54323) で変更を作成
# 2. 差分からマイグレーションを生成
supabase db diff -f <migration_name>

# 3. 生成された SQL を確認
cat supabase/migrations/*_<migration_name>.sql

# 4. テストのためリセット
supabase db reset

オプション 2: マイグレーションを直接記述 (推奨)

# 1. 空のマイグレーションを作成
supabase migration new create_users_table

# 2. マイグレーションファイルを編集
# supabase/migrations/<timestamp>_create_users_table.sql

# 3. ローカルに適用
supabase db reset

オプション 3: ORM マイグレーション (Best DX)

Drizzle (TypeScript) または SQLAlchemy (Python) を使用 - フレームワーク固有のスキルを参照。

マイグレーションをデプロイ

# リモート (ステージング/本番) にプッシュ
supabase db push

# マイグレーション状態を確認
supabase migration list

---

データベース パターン

すべてのテーブルで RLS を有効化

-- 常に RLS を有効化
ALTER TABLE public.profiles ENABLE ROW LEVEL SECURITY;

-- デフォルトで拒否 - ポリシーを作成する必要がある
CREATE POLICY "Users can view own profile"
  ON public.profiles
  FOR SELECT
  USING (auth.uid() = id);

一般的な RLS ポリシー

-- 公開読み取り
CREATE POLICY "Public read access"
  ON public.posts FOR SELECT
  USING (true);

-- 認証済みユーザーのみ
CREATE POLICY "Authenticated users can insert"
  ON public.posts FOR INSERT
  WITH CHECK (auth.role() = 'authenticated');

-- オーナーアクセス
CREATE POLICY "Users can update own records"
  ON public.posts FOR UPDATE
  USING (auth.uid() = user_id);

-- 管理者アクセス (カスタムクレームを使用)
CREATE POLICY "Admins have full access"
  ON public.posts FOR ALL
  USING (auth.jwt() ->> 'role' = 'admin');

auth.users にリンク

-- 認証にリンクされたプロフィールテーブル
CREATE TABLE public.profiles (
  id UUID PRIMARY KEY REFERENCES auth.users(id) ON DELETE CASCADE,
  username TEXT UNIQUE NOT NULL,
  avatar_url TEXT,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- サインアップ時に自動プロフィール作成
CREATE OR REPLACE FUNCTION public.handle_new_user()
RETURNS TRIGGER AS $$
BEGIN
  INSERT INTO public.profiles (id, username)
  VALUES (NEW.id, NEW.email);
  RETURN NEW;
END;
$$ LANGUAGE plpgsql SECURITY DEFINER;

CREATE TRIGGER on_auth_user_created
  AFTER INSERT ON auth.users
  FOR EACH ROW EXECUTE FUNCTION public.handle_new_user();

---

シードデータ

supabase/seed.sql

-- `supabase db reset` で実行される
-- べき等性のため ON CONFLICT を使用

INSERT INTO public.profiles (id, username, avatar_url)
VALUES
  ('d0e1f2a3-b4c5-6d7e-8f9a-0b1c2d3e4f5a', 'testuser', null),
  ('a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d', 'admin', null)
ON CONFLICT (id) DO NOTHING;

---

環境変数

必須変数

# 公開 (クライアント側で安全)
SUPABASE_URL=https://xxxxx.supabase.co
SUPABASE_ANON_KEY=eyJ...

# プライベート (サーバー側のみ - 絶対に公開しない)
SUPABASE_SERVICE_ROLE_KEY=eyJ...
DATABASE_URL=postgresql://postgres.[ref]:[password]@aws-0-region.pooler.supabase.com:6543/postgres

ローカル vs 本番

# .env.local (ローカル開発)
SUPABASE_URL=http://localhost:54321
SUPABASE_ANON_KEY=<from supabase start>
DATABASE_URL=postgresql://postgres:postgres@localhost:54322/postgres

# .env.production (リモート)
SUPABASE_URL=https://xxxxx.supabase.co
SUPABASE_ANON_KEY=<from dashboard>
DATABASE_URL=<connection pooler URL>

コネクションプーリング

# トランザクションモード (サーバーレスに推奨)
# URL に ?pgbouncer=true を追加
DATABASE_URL=postgresql://...@pooler.supabase.com:6543/postgres?pgbouncer=true

# セッションモード (マイグレーション、長いトランザクション向け)
DATABASE_URL=postgresql://...@pooler.supabase.com:5432/postgres

---

Edge Functions

関数を作成

supabase functions new hello-world

基本的な構造

// supabase/functions/hello-world/index.ts
import { serve } from 'https://deno.land/std@0.168.0/http/server.ts';

serve(async (req) => {
  const { name } = await req.json();

  return new Response(
    JSON.stringify({ message: `Hello ${name}!` }),
    { headers: { 'Content-Type': 'application/json' } }
  );
});

認証コンテキスト付き

import { serve } from 'https://deno.land/std@0.168.0/http/server.ts';
import { createClient } from 'https://esm.sh/@supabase/supabase-js@2';

serve(async (req) => {
  const supabase = createClient(
    Deno.env.get('SUPABASE_URL') ?? '',
    Deno.env.get('SUPABASE_ANON_KEY') ?? '',
    {
      global: {
        headers: { Authorization: req.headers.get('Authorization')! },
      },
    }
  );

  const { data: { user } } = await supabase.auth.getUser();

  if (!user) {
    return new Response('Unauthorized', { status: 401 });
  }

  return new Response(JSON.stringify({ user_id: user.id }));
});

デプロイ

# ローカルで提供
supabase functions serve

# 単一関数をデプロイ
supabase functions deploy hello-world

# すべてをデプロイ
supabase functions deploy

---

Storage

バケットを作成 (マイグレーション内)

INSERT INTO storage.buckets (id, name, public)
VALUES ('avatars', 'avatars', true);

-- ストレージポリシー
CREATE POLICY "Avatar images are publicly accessible"
  ON storage.objects FOR SELECT
  USING (bucket_id = 'avatars');

CREATE POLICY "Users can upload own avatar"
  ON storage.objects FOR INSERT
  WITH CHECK (
    bucket_id = 'avatars' AND
    auth.uid()::text = (storage.foldername(name))[1]
  );

---

CLI クイックリファレンス

# ライフサイクル
supabase start                   # ローカルスタックを起動
supabase stop                    # ローカルスタックを停止
supabase status                  # ステータスと認証情報を表示

# データベース
supabase db reset                # リセット + マイグレーション + シード
supabase db push                 # リモートにプッシュ
supabase db pull                 # リモートスキーマを取得
supabase db diff -f <name>       # 差分からマイグレーションを生成
supabase db lint                 # 問題をチェック

# マイグレーション
supabase migration new <name>    # マイグレーションを作成
supabase migration list          # マイグレーション一覧
supabase migration up            # 未適用を適用 (リモート)

# 関数
supabase functions new <name>    # 関数を作成
supabase functions serve         # ローカル開発
supabase functions deploy        # すべてをデプロイ

# 型
supabase gen types typescript --local > types/database.ts

# プロジェクト
supabase link --project-ref <id> # リモートにリンク
supabase projects list           # プロジェクト一覧

---

CI/CD テンプレート

# .github/workflows/supabase.yml
name: Supabase CI/CD

on:
  push:
    branches: [main]
  pull_request:

env:
  SUPABASE_ACCESS_TOKEN: ${{ secrets.SUPABASE_ACCESS_TOKEN }}
  SUPABASE_DB_PASSWORD: ${{ secrets.SUPABASE_DB_PASSWORD }}
  SUPABASE_PROJECT_ID: ${{ secrets.SUPABASE_PROJECT_ID }}

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: supabase/setup-cli@v1

      - name: Start Supabase
        run: supabase start

      - name: Run migrations
        run: supabase db reset

      - name: Lint database
        run: supabase db lint

  deploy:
    needs: test
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: supabase/setup-cli@v1

      - name: Link project
        run: supabase link --project-ref $SUPABASE_PROJECT_ID

      - name: Push migrations
        run: supabase db push

      - name: Deploy functions
        run: supabase functions deploy

---

アンチパターン

• 本番環境への直接変更 - 常にマイグレーションを使用
• RLS が無効 - ユーザーデータを扱うすべてのテーブルで有効化
• クライアント内のサービスキー - サービスロールキーを絶対に公開しない
• コネクションプーリングなし - サーバーレスではプーラーを使用
• .env をコミット - .gitignore に追加
• マイグレーション確認をスキップ - 常に生成された SQL をチェック
• シードデータなし - 一貫性のあるローカル開発のため seed.sql を使用