概要

SupabaseはPostgreSQLをコアに、認証・ストレージ・Realtimeをまとめて提供するOSSのBaaS。FirebaseのOSS代替として作られたが、リレーショナルDBを直接使える点が最大の違い。

• PostgreSQLの全機能（SQL・トランザクション・RLS・トリガー）がそのまま使える
• 認証・Storage・Realtime・Edge Functionsがセットで提供される
• ローカル開発はDockerで本番と同じ環境を再現でき、マイグレーションはSQLファイルで管理する

1. Supabaseとは

FirebaseのOSS代替。最大の違いはPostgreSQLを直接使えること。

SupabaseはPostgreSQLを中心に、認証・ストレージ・Realtime・Edge Functionsをまとめて提供するBaaS（Backend as a Service）。 Firebaseと同じ立ち位置だが、FirebaseがNoSQL（ドキュメント型）なのに対し、SupabaseはリレーショナルDB（PostgreSQL）を使う。 OSSなので自分でホストも可能だが、通常はSupabase社のクラウドを利用する。

あなたのアプリ
    ↓
Supabase（認証 / DB / Storage / Realtime / Edge Functions）
    ↓
PostgreSQL（実体）

💡 ポイント: 「SupabaseはPostgresのラッパー」と覚えると本質を見失わない。JoinもトランザクションもRLSも使えるのはPostgreSQLだから。

用語

2. アーキテクチャ概観

Supabaseは複数のOSSを組み合わせたスタックで、PostgreSQLを中心に動いている。

各機能は独立したOSSプロダクトの組み合わせ。テーブルを作るだけで自動的にREST APIが生えるのはPostgRESTのおかげ。

┌─────────────────────────────────┐
│          あなたのアプリ           │
└────────────┬────────────────────┘
             ↓
┌─────────────────────────────────┐
│         Supabase API層           │
│  PostgREST │ GoTrue │ Realtime  │
│  Storage   │ Edge Functions      │
└────────────┬────────────────────┘
             ↓
┌─────────────────────────────────┐
│         PostgreSQL               │
└─────────────────────────────────┘

💡 ポイント: supabase-jsのクエリは内部的にPostgRESTへのHTTPリクエスト。DjangoのModelViewSetが自動生成されるイメージ。

// これは内部的にPostgRESTへのGETリクエスト
const { data } = await supabase.from('posts').select('*')

用語

3. プロジェクト構成とセットアップ

ダッシュボード・CLI・ローカル開発（Docker）の3つを使い分ける。

ローカル開発ではsupabase startでDockerコンテナが自動起動し、本番と同じ環境が再現される。 Dockerは「PCの中に小さい仮想マシンを立てるツール」で、Docker Desktopをインストールして起動しておくだけでよい。 スキーマ変更はSQLファイルで管理し、db diff→db pushの流れで本番に反映する。

supabase/
├── config.toml        # ローカル設定
├── migrations/        # マイグレーションSQL
│   └── 20240101_init.sql
└── seed.sql           # 初期データ

# セットアップ
brew install --cask docker   # Docker Desktopをインストール
supabase init                # プロジェクト初期化
supabase start               # Docker起動（DB・Auth・Storageが全部立ち上がる）

# 開発フロー
supabase db diff -f add_posts_table   # 差分からマイグレーション生成
git add supabase/migrations/
git commit -m "add posts table"
supabase db push                      # 本番DBに適用

開発フロー：
ローカルDB（Docker）でスキーマ変更（GUIかSQL直書き）
    ↓ db diff
migrations/20240101_add_posts.sql（自動生成）
    ↓ git commit
Gitリポジトリ
    ↓ db push
本番DB（Supabase Cloud）

💡 ポイント: supabase linkで本番プロジェクトと紐づけておく必要がある（初回のみ）。GUIで作ったテーブルもdb diffで拾えるので「まずGUIで試してからSQLに落とす」順番もアリ。

Djangoとの比較

用語

4. データベース（PostgreSQL）

SupabaseのDBは本物のPostgreSQLなので、SQLの全機能がそのまま使える。

テーブル作成はダッシュボードのGUIか直接SQLで行う。 Djangoと違いモデル定義ファイルは存在せず、マイグレーションはSQLファイルで管理する。 確認・閲覧はダッシュボードのTable EditorでGUI確認するのが基本。

-- supabase/migrations/20240101_create_posts.sql
CREATE TABLE posts (
  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  title TEXT NOT NULL,
  body TEXT,
  user_id UUID REFERENCES auth.users(id),
  created_at TIMESTAMPTZ DEFAULT NOW()
);

💡 ポイント: auth.usersはSupabaseが自動で作るテーブル。外部キーで参照することでユーザーとデータを紐づけられる。スキーマはSQLファイルで管理（Git管理）し、確認はダッシュボードのTable Editorで行うのが実用的。

Djangoとの比較

5. Row Level Security（RLS）

テーブルに「誰がどの行を読み書きできるか」をDB側で定義するPostgreSQLの機能。

RLSを有効にするとデフォルトで全行へのアクセスが拒否される（ホワイトリスト方式）。 ポリシーを追加することで「自分の行だけ読める」などのルールを定義する。 アプリ側でフィルタリングするより安全で、バグによる情報漏洩を防げる。

-- RLSを有効化
ALTER TABLE posts ENABLE ROW LEVEL SECURITY;

-- 自分の投稿だけ読めるポリシー
CREATE POLICY "自分の投稿を読める"
ON posts FOR SELECT
USING (auth.uid() = user_id);

RLS ON + ポリシーなし → 全拒否
RLS ON + ポリシーあり → ポリシーに合致した行だけ許可
RLS OFF           → 全員全行アクセス可能（危険）

💡 ポイント: 新しいテーブルを作ったらまずRLSをONにするを習慣にする。service_role_keyはRLSをバイパスできるため、絶対にフロントエンドに渡してはいけない（NEXT_PUBLIC_禁止）。

用語

6. 認証（Auth）

JWTベースの認証で、ログイン状態はトークンで管理される。

メール・パスワード、OAuth（Google・GitHubなど）に対応。 ログインするとJWTが発行され、以降のリクエストにそのトークンが自動付与される。 RLSのauth.uid()はJWTに埋め込まれたsubフィールド（ユーザーID）を取り出して使っている。

// サインアップ
await supabase.auth.signUp({ email, password })

// ログイン
await supabase.auth.signInWithPassword({ email, password })

// 現在のユーザー取得
const { data: { user } } = await supabase.auth.getUser()

ログイン
  ↓
JWT発行（中にuser_idが埋め込まれている）
  ↓
以降のリクエストにJWTを付与
  ↓
PostgreSQL側でauth.uid()がJWTからIDを取り出す
  ↓
RLSポリシーで照合

💡 ポイント: Next.jsのServer ComponentsでJWTを使う場合はCookie経由でトークンを渡す必要がある。LocalStorageはサーバー側からアクセスできないため。

Djangoとの比較

7. Storage

ファイルをバケット単位で管理し、RLSと同じ仕組みでアクセス制御できる。

画像・動画・PDFなどのファイルをSupabase上に保存できる。 バケット単位でパブリック・プライベートを選択でき、アクセス制御はRLSポリシーと同じ構文で書ける。 AWSのS3と役割は同じだが、PostgreSQLのRLSと統合されているため一貫したアクセス制御が可能。

// ファイルアップロード
await supabase.storage
  .from('avatars')
  .upload('user123/avatar.png', file)

// 公開URLの取得（期限なし）
const { data } = supabase.storage
  .from('avatars')
  .getPublicUrl('user123/avatar.png')

// 期限付きURL（60秒間有効）
const { data } = await supabase.storage
  .from('documents')
  .createSignedUrl('secret.pdf', 60)

💡 ポイント: getPublicUrlは期限なし（パブリックバケット用）、createSignedUrlは期限あり（プライベートバケット用）。有料コンテンツの一時配布などはcreateSignedUrlを使う。

用語

8. Edge Functions

Deno製のサーバーレス関数で、Supabase内で完結させたい処理の受け口に使う。

TypeScriptで書けてDenoランタイムで動作する。Vercelのサーバーレス関数に近い存在。 Next.js + Honoスタックがある場合、APIルートはそちらに書くのが自然で、Edge Functionsの出番は限られる。 「Supabaseのトリガーと連携」「Stripe Webhookの受信」「定期バッチ処理」など、Supabase内で完結する処理に絞るのが適切。

// supabase/functions/hello/index.ts
Deno.serve(async (req) => {
  const { name } = await req.json()
  return new Response(
    JSON.stringify({ message: `Hello ${name}` }),
    { headers: { 'Content-Type': 'application/json' } }
  )
})

supabase functions serve hello   # ローカルで実行
supabase functions deploy hello  # 本番デプロイ

💡 ポイント: Next.js + Honoがある場合、Edge Functionsは「Supabaseのイベントに反応する処理の受け口」と位置づけると役割が明確になる。

用途

9. Realtime

WebSocketを使ってDBの変更をリアルタイムでクライアントに配信する仕組み。

PostgreSQLの変更（INSERT・UPDATE・DELETE）をリアルタイムで検知してクライアントに届ける。 Next.jsではServer Componentsがリクエスト単位で終わるため、WebSocket接続を維持できるClient Componentで実装する必要がある。 RLSが有効な場合、Realtimeも自動でRLSに従い、自分に関係ない行の変更は届かない。

'use client' // これが必須

import { useEffect } from 'react'
import { supabase } from '@/lib/supabase'

export default function PostList() {
  useEffect(() => {
    const channel = supabase
      .channel('posts-channel')
      .on(
        'postgres_changes',
        { event: 'INSERT', schema: 'public', table: 'posts' },
        (payload) => {
          console.log('新しい投稿:', payload.new)
        }
      )
      .subscribe()

    return () => { channel.unsubscribe() } // クリーンアップ必須
  }, [])
}

💡 ポイント: useEffectの返り値でクリーンアップを忘れると、コンポーネントが消えてもWebSocket接続が残り続けてしまう。

イベント一覧

10. クライアントSDK（JS/TS）

supabase-jsはPostgREST・Auth・Storage・RealtimeをまとめてラップしたSDK。

Next.jsでは「サーバー側」と「クライアント側」でクライアントの作り方を分ける必要がある。 サーバー側はLocalStorageにアクセスできないため、@supabase/ssrパッケージを使いCookie経由でセッションを引き継ぐ。

// lib/supabase/server.ts（Server Components・Route Handlers用）
import { createServerClient } from '@supabase/ssr'
import { cookies } from 'next/headers'

export const createClient = () => createServerClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
  { cookies: { getAll: () => cookies().getAll() } }
)

// lib/supabase/client.ts（Client Components用）
import { createBrowserClient } from '@supabase/ssr'

export const createClient = () => createBrowserClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
)

💡 ポイント: NEXT_PUBLIC_が付くのはURLとANON_KEYだけ。SERVICE_ROLE_KEYは絶対にNEXT_PUBLIC_にしてはいけない（RLSをバイパスできるため）。

用途別クライアント

11. 無料枠の制約と本番運用の注意点

無料枠は共有CPUで遅く、非アクティブ停止があるため本番運用には向かない。

無料枠（Nanoインスタンス）は共有CPUのため、他ユーザーの影響を受けてレスポンスが遅くなることがある。 本番ではProプラン（Microインスタンス・専有CPU）以上が必須。非アクティブ停止は本番では致命的。

無料枠の主な制約：
├── プロジェクト数：最大2つまで
├── DB容量：500MB
├── Storage：1GB
├── Edge Functions：500,000回/月
├── 非アクティブ停止：7日間で一時停止
└── CPU・メモリ：共有CPU / 500MB RAM（Nanoインスタンス）

💡 ポイント: Proには$10のコンピュートクレジットが付くので実質$25でMicroインスタンスが使える。2プロジェクトは本番・開発で1つずつ使い切るのが現実的。

❌ やりがちなミス

環境変数の扱いとRLS設定漏れが最も危険なミス。

📝 自分のメモ・気づき

セッション全体を通じて、SupabaseはPostgreSQLの強さをそのまま活かせる設計になっている点が重要。

• FirebaseはNoSQL（ドキュメント型）、SupabaseはPostgreSQL（リレーショナル）が最大の違い
• PostgRESTにより、テーブルを作るだけで自動でREST APIが生える。supabase-jsはそのHTTPラッパー
• supabase startはDockerで本番と同じ環境をローカルに再現する。Docker Desktopを入れておくだけでよく、Docker知識はほぼ不要
• マイグレーションはDjangoのmakemigrations→migrateに相当するdb diff→db pushで管理する。出力がSQLそのものなので読みやすい
• GUIでテーブルをポチポチ作ってもdb diffで拾えるので「まずGUIで試してからSQLに落とす」順番もアリ
• RLSはホワイトリスト方式。有効化しただけでは全拒否。ポリシーを追加することで許可する
• auth.uid()はJWTのsubフィールドからユーザーIDを取り出している
• Next.jsではServer ComponentはCookie経由（createServerClient）、Client ComponentはLocalStorage/Cookie（createBrowserClient）でセッション管理が異なる
• 無料枠は共有CPU（Nano）のため他ユーザーの影響を受けて遅くなることがある。本番は専有CPU（Micro以上）が必須
• Edge FunctionsはNext.js + Honoスタックでは出番が限られる。「Supabaseのイベントに反応する処理」の受け口と位置づけるのが明確

参考リンク

• Supabase公式ドキュメント
• Supabase料金プラン
• Supabase CLI リファレンス
• @supabase/ssr ドキュメント
• Compute and Disk | Supabase Docs