【2026年版】Supabase本番運用ガイド：公式ドキュメント準拠でNext.js × RLS × Realtime × Edge Functionsを実装する

# .env.local
NEXT_PUBLIC_SUPABASE_URL=<your-project-url>
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=<your-publishable-key>

npm install @supabase/supabase-js @supabase/ssr

// lib/supabase/client.ts
import { createBrowserClient } from "@supabase/ssr";

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

// lib/supabase/server.ts
import { createServerClient } from "@supabase/ssr";
import { cookies } from "next/headers";

export async function createClient() {
  const cookieStore = await cookies();

  return createServerClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY!,
    {
      cookies: {
        getAll() {
          return cookieStore.getAll();
        },
        setAll(cookiesToSet) {
          try {
            cookiesToSet.forEach(({ name, value, options }) =>
              cookieStore.set(name, value, options),
            );
          } catch {
            // Server Component から setAll が呼ばれたケース。
            // ミドルウェアでセッションを更新しているなら無視してよい。
          }
        },
      },
    },
  );
}

// lib/supabase/middleware.ts
import { createServerClient } from "@supabase/ssr";
import { NextResponse, type NextRequest } from "next/server";

export async function updateSession(request: NextRequest) {
  let supabaseResponse = NextResponse.next({ request });

  const supabase = createServerClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY!,
    {
      cookies: {
        getAll() {
          return request.cookies.getAll();
        },
        setAll(cookiesToSet) {
          cookiesToSet.forEach(({ name, value }) =>
            request.cookies.set(name, value),
          );
          supabaseResponse = NextResponse.next({ request });
          cookiesToSet.forEach(({ name, value, options }) =>
            supabaseResponse.cookies.set(name, value, options),
          );
        },
      },
    },
  );

  // 重要：ここでセッション（トークン）をリフレッシュする
  const {
    data: { user },
  } = await supabase.auth.getUser();

  // 未認証ユーザーを保護ページから弾くリダイレクトはここに書く
  if (!user && request.nextUrl.pathname.startsWith("/app")) {
    const url = request.nextUrl.clone();
    url.pathname = "/login";
    return NextResponse.redirect(url);
  }

  return supabaseResponse;
}

// middleware.ts
import { type NextRequest } from "next/server";
import { updateSession } from "@/lib/supabase/middleware";

export async function middleware(request: NextRequest) {
  return await updateSession(request);
}

export const config = {
  matcher: ["/((?!_next/static|_next/image|favicon.ico|.*\\.svg$).*)"],
};

// Server Component / Route Handler での認可
import { createClient } from "@/lib/supabase/server";

export default async function DashboardPage() {
  const supabase = await createClient();

  // 推奨：getClaims()（非対称鍵ならローカル検証で高速）
  const { data, error } = await supabase.auth.getClaims();
  if (error || !data) redirect("/login");

  const userId = data.claims.sub;
  // …userId を根拠に認可・データ取得
}

-- まずテーブルでRLSを有効化（これを忘れると全公開）
alter table public.todos enable row level security;

create policy "<ポリシー名>"
on <テーブル>
for <select | insert | update | delete | all>
to <ロール>                  -- 例: authenticated, anon
using (<可視性・対象の条件>)   -- SELECT/UPDATE/DELETE：既存行のフィルタ
with check (<書き込み値の検証>); -- INSERT/UPDATE：新しい行の値の検証

-- SELECT：自分のtodoだけ見える
create policy "Individuals can view their own todos."
on public.todos for select
using ( (select auth.uid()) = user_id );

-- INSERT：自分名義でだけ作成できる
create policy "Users can create a profile."
on public.profiles for insert
to authenticated
with check ( (select auth.uid()) = user_id );

-- UPDATE：using と with check の両方が要る
create policy "Users can update their own profile."
on public.profiles for update
to authenticated
using ( (select auth.uid()) = user_id )
with check ( (select auth.uid()) = user_id );

-- DELETE
create policy "Users can delete their own profile."
on public.profiles for delete
to authenticated
using ( (select auth.uid()) = user_id );

create policy "Restrict updates to MFA users."
on public.profiles
as restrictive
for update
to authenticated
using ( (select auth.jwt()->>'aal') = 'aal2' );

-- ①インデックス
create index idx_todos_user_id on public.todos using btree (user_id);

create function public.hello_world()
returns text
language plpgsql
security definer set search_path = ''  -- 必須。空にしたら関数内は public.table と明示する
as $$
begin
  return 'hello world';
end;
$$;

-- 1) ロールと権限の型・テーブル
create type public.app_permission as enum ('channels.delete', 'messages.delete');
create type public.app_role as enum ('admin', 'moderator');

create table public.user_roles (
  id      bigint generated by default as identity primary key,
  user_id uuid references auth.users on delete cascade not null,
  role    app_role not null,
  unique (user_id, role)
);

-- 2) トークン発行前に user_role をクレームへ注入するフック
create or replace function public.custom_access_token_hook(event jsonb)
returns jsonb
language plpgsql
stable
as $$
declare
  claims jsonb;
  user_role public.app_role;
begin
  select role into user_role from public.user_roles
  where user_id = (event->>'user_id')::uuid;

  claims := event->'claims';
  if user_role is not null then
    claims := jsonb_set(claims, '{user_role}', to_jsonb(user_role));
  else
    claims := jsonb_set(claims, '{user_role}', 'null');
  end if;

  event := jsonb_set(event, '{claims}', claims);
  return event;
end;
$$;

-- 3) フックは supabase_auth_admin として実行される。権限を厳格に絞る
grant usage on schema public to supabase_auth_admin;
grant execute on function public.custom_access_token_hook to supabase_auth_admin;
revoke execute on function public.custom_access_token_hook from authenticated, anon, public;
grant all on table public.user_roles to supabase_auth_admin;
revoke all on table public.user_roles from authenticated, anon, public;

create policy "Allow auth admin to read user roles" on public.user_roles
as permissive for select to supabase_auth_admin using (true);

create or replace function public.authorize(requested_permission app_permission)
returns boolean
language plpgsql
stable
security definer set search_path = ''
as $$
declare
  bind_permissions int;
  user_role public.app_role;
begin
  select (auth.jwt() ->> 'user_role')::public.app_role into user_role;
  select count(*) into bind_permissions
  from public.role_permissions
  where permission = requested_permission and role = user_role;
  return bind_permissions > 0;
end;
$$;

create policy "Allow authorized delete" on public.channels
for delete to authenticated
using ( (select authorize('channels.delete')) );

import { createClient } from "@supabase/supabase-js";
const supabase = createClient("<url>", "<publishable-key>");

const channel = supabase.channel("room-1");

// 受信
channel
  .on("broadcast", { event: "shout" }, (payload) => console.log(payload))
  .subscribe((status) => {
    if (status !== "SUBSCRIBED") return;
    // 送信（subscribe後はWebSocket経由）
    channel.send({ type: "broadcast", event: "shout", payload: { message: "Hi" } });
  });

create or replace function public.your_table_changes()
returns trigger
security definer
language plpgsql
as $$
begin
  perform realtime.broadcast_changes(
    'topic:' || coalesce(NEW.id, OLD.id)::text, -- トピック
    TG_OP,                                      -- event
    TG_OP,                                      -- operation
    TG_TABLE_NAME,
    TG_TABLE_SCHEMA,
    NEW,
    OLD
  );
  return null;
end;
$$;

create trigger handle_your_table_changes
after insert or update or delete on public.your_table
for each row execute function public.your_table_changes();

const gameId = "abc";
await supabase.realtime.setAuth(); // Realtimeの認可トークンを更新（プライベートチャネルに必須）

const channel = supabase
  .channel(`topic:${gameId}`, { config: { private: true } })
  .on("broadcast", { event: "INSERT" }, (p) => console.log(p))
  .on("broadcast", { event: "UPDATE" }, (p) => console.log(p))
  .on("broadcast", { event: "DELETE" }, (p) => console.log(p))
  .subscribe();

-- 例：そのルームのメンバーだけ受信を許可
create policy "Members can receive room broadcasts"
on "realtime"."messages"
for select
to authenticated
using (
  exists (
    select 1 from public.rooms_users
    where user_id = (select auth.uid())
      and room_topic = (select realtime.topic())
      and realtime.messages.extension in ('broadcast', 'presence')
  )
);

const room = supabase.channel("room-1");
room
  .on("presence", { event: "sync" }, () => console.log(room.presenceState()))
  .on("presence", { event: "join" }, ({ key, newPresences }) => console.log("join", key))
  .on("presence", { event: "leave" }, ({ key, leftPresences }) => console.log("leave", key))
  .subscribe(async (status) => {
    if (status !== "SUBSCRIBED") return;
    await room.track({ user: "user-1", online_at: new Date().toISOString() });
  });

import { withSupabase } from "npm:@supabase/server";

export default {
  fetch: withSupabase({ auth: ["publishable", "secret"] }, async (req, ctx) => {
    const { name } = await req.json();
    return Response.json({ message: `Hello ${name}!` });
  }),
};

import { withSupabase } from "npm:@supabase/server";

export default {
  fetch: withSupabase({ auth: "user" }, async (_req, ctx) => {
    const { supabase, supabaseAdmin, userClaims, jwtClaims, authMode } = ctx;
    // supabase      … 認証ユーザーにRLSスコープされたクライアント
    // supabaseAdmin … RLSをバイパス（service role）。取り扱い注意
    // userClaims    … JWTから得たユーザー識別（id, email, role）
    return Response.json({ email: ctx.userClaims?.email });
  }),
};

supabase functions new hello-world      # 雛形生成
supabase start                          # ローカルスタック（Docker）
supabase functions serve hello-world    # ローカル実行
supabase functions deploy hello-world   # デプロイ（名前省略で全関数）
# supabase functions deploy --use-api   # Docker不要のAPI経由デプロイ

// アップロード（upsertやcontentTypeも指定可）
await supabase.storage.from("avatars").upload("public/avatar1.png", file, {
  upsert: true,
  contentType: "image/png",
});

// 公開バケットのURL
const { data } = supabase.storage.from("avatars").getPublicUrl("public/avatar1.png");

// 非公開ファイルの時間制限つき署名URL（秒指定）
const { data: signed } = await supabase.storage
  .from("private-docs")
  .createSignedUrl("contract.pdf", 3600); // 1時間

-- 各ユーザーは「自分のIDフォルダ」にだけアップロードできる
create policy "Users upload to their own folder"
on storage.objects for insert to authenticated
with check (
  bucket_id = 'avatars'
  and (storage.foldername(name))[1] = (select auth.jwt()->>'sub')
);

-- 自分が所有するオブジェクトだけ閲覧できる
create policy "Owner can read"
on storage.objects for select to authenticated
using ( (select auth.jwt()->>'sub') = owner_id );

-- 1) 拡張を有効化（extensions スキーマに）
create extension vector with schema extensions;

-- 2) 埋め込み列（次元数はモデルの出力に一致させる）
create table documents (
  id serial primary key,
  title text not null,
  body text not null,
  embedding extensions.vector(384)
);

create or replace function match_documents (
  query_embedding extensions.vector(384),
  match_threshold float,
  match_count int
)
returns table (id bigint, title text, body text, similarity float)
language sql stable
as $$
  select
    documents.id, documents.title, documents.body,
    1 - (documents.embedding <=> query_embedding) as similarity
  from documents
  where 1 - (documents.embedding <=> query_embedding) > match_threshold
  order by documents.embedding <=> query_embedding asc
  limit match_count;
$$;

const { data } = await supabase.rpc("match_documents", {
  query_embedding: embedding, // クエリ文を埋め込んだベクトル
  match_threshold: 0.78,
  match_count: 10,
});

create index on documents using hnsw (embedding vector_cosine_ops);

-- 2,000次元超は halfvec へキャストして索引化
create index on documents using hnsw ((embedding::halfvec(3072)) halfvec_cosine_ops);

supabase migration new create_employees_table   # 手書きマイグレーション
supabase db diff -f create_cities_table          # 宣言的スキーマから差分生成
supabase migration up                            # ローカル適用
supabase db push                                 # リモートへ反映