supabase-skill

Supabase MCP 技能

概述

本技能提供通过 Model Context Protocol (MCP) 使用 Supabase 的全面指南，支持 AI 驱动的数据库操作、现代化架构设计以及可用于生产环境的数据库架构。

何时使用本技能

遇到以下任意情况时，请使用本技能：

设置与配置

• 设置或配置 Supabase MCP 服务（Cursor、Claude Desktop、Claude Code CLI）
• 将 AI 工具连接到 Supabase 项目
• 调试 MCP 连接问题
• 配置只读模式、项目范围或功能组

数据库设计

• 遵循最佳实践设计数据库架构
• 实现表关系（一对多、多对多、多态）
• 选择规范化模式（单表继承或类表继承）
• 设计多租户或微服务架构
• 处理时态数据或审计日志

安全与访问控制

• 实施行级安全（RLS）策略
• 设置与 auth.users 的身份验证集成
• 构建基于角色的访问控制（RBAC）
• 保护多租户应用
• 防止未经授权的数据访问

迁移与架构演进

• 创建和管理数据库迁移
• 演进架构，同时避免破坏性变更
• 处理向后兼容性
• 使用 Supabase 分支进行测试

生产环境模式

• 使用超时逻辑进行会话管理
• 内存持久化模式（使用 soul + process memory 双重持久化）
• 按区域组织消息存储
• 带验证的状态管理
• 错误处理与优雅降级

性能与优化

• 提升查询性能的索引策略
• 使用 EXPLAIN ANALYZE 优化查询
• 配置连接池
• 设置只读副本以扩展规模

快速参考示例

1. MCP 服务设置（Claude Code CLI）

# Basic installation with project scoping
claude mcp add --transport stdio \
  --env SUPABASE_ACCESS_TOKEN=your_personal_access_token \
  --scope local \
  supabase -- npx -y @supabase/mcp-server-supabase@latest \
  --project-ref=your_project_ref

# With read-only mode (safe for exploration)
claude mcp add --transport stdio \
  --env SUPABASE_ACCESS_TOKEN=your_token \
  --scope local \
  supabase -- npx -y @supabase/mcp-server-supabase@latest \
  --project-ref=your_project_ref \
  --read-only

2. Supabase 单例客户端（TypeScript）

import { createClient, SupabaseClient } from '@supabase/supabase-js';

let supabaseClient: SupabaseClient | null = null;

export function getSupabaseClient(): SupabaseClient {
  if (!supabaseClient) {
    const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL;
    const supabaseServiceKey = process.env.SUPABASE_SERVICE_KEY;

    if (!supabaseUrl || !supabaseServiceKey) {
      throw new Error('Missing Supabase environment variables');
    }

    supabaseClient = createClient(supabaseUrl, supabaseServiceKey, {
      auth: {
        autoRefreshToken: false,  // Server-side: no refresh needed
        persistSession: false,     // Server-side: no persistence
      },
    });
  }

  return supabaseClient;
}

3. 使用 RLS 的用户资料（SQL）

-- Create profiles table linked to auth.users
create table public.profiles (
  id uuid references auth.users(id) primary key,
  username text unique not null,
  full_name text,
  avatar_url text,
  created_at timestamptz default now()
);

-- Enable RLS
alter table public.profiles enable row level security;

-- Allow anyone to view profiles
create policy "Users can view all profiles"
  on public.profiles for select
  using (true);

-- Users can only update their own profile
create policy "Users can update own profile"
  on public.profiles for update
  using (auth.uid() = id);

4. 使用 RLS 的多租户组织

-- Organizations table
create table public.organizations (
  id uuid primary key default gen_random_uuid(),
  name text not null,
  slug text unique not null
);

-- Organization members junction table
create table public.org_members (
  org_id uuid references public.organizations(id) on delete cascade,
  user_id uuid references auth.users(id) on delete cascade,
  role text not null check (role in ('owner', 'admin', 'member')),
  primary key (org_id, user_id)
);

-- RLS: Users can only see organizations they're members of
alter table public.organizations enable row level security;

create policy "Users can view own organizations"
  on public.organizations for select
  using (
    exists (
      select 1 from public.org_members
      where org_members.org_id = organizations.id
      and org_members.user_id = auth.uid()
    )
  );

5. 会话加载或创建模式

// Load existing session or create new one
const { data: existing, error: fetchError } = await supabase
  .from('user_sessions')
  .select('*')
  .eq('phone_number', phoneNumber)
  .single();

// Handle "no rows returned" as valid (not an error)
if (fetchError && fetchError.code !== 'PGRST116') {
  throw new Error(`Failed to load session: ${fetchError.message}`);
}

if (existing) {
  // Update existing session
  await supabase
    .from('user_sessions')
    .update({ last_active_at: new Date().toISOString() })
    .eq('id', existing.id);

  return existing;
}

// Create new session if none exists
const { data: newSession } = await supabase
  .from('user_sessions')
  .insert({ phone_number: phoneNumber })
  .select()
  .single();

return newSession;

6. 键值存储的 Upsert 模式

// Save or update soul memory (upsert pattern)
const { data, error } = await supabase
  .from('soul_memories')
  .upsert(
    {
      session_id: sessionId,
      key: 'user_name',
      value: { firstName: 'Alice', lastName: 'Smith' },
      updated_at: new Date().toISOString(),
    },
    { onConflict: 'session_id,key' }  // Composite unique constraint
  )
  .select()
  .single();

7. 时态数据模式（历史记录跟踪）

-- Products with full history tracking
create table public.products_history (
  id uuid not null,
  name text not null,
  price numeric(10,2) not null,

  -- Temporal columns
  valid_from timestamptz not null default now(),
  valid_to timestamptz,  -- null = current version

  -- Audit columns
  changed_by uuid references auth.users(id),
  change_reason text,

  primary key (id, valid_from)
);

-- View for current products only
create view public.products as
select id, name, price
from public.products_history
where valid_to is null;

8. 用于分析的物化视图

-- Aggregate analytics data for fast queries
create materialized view public.orders_analytics as
select
  date_trunc('day', created_at) as order_date,
  count(*) as total_orders,
  sum(total) as revenue,
  avg(total) as avg_order_value
from public.orders
where status = 'completed'
group by date_trunc('day', created_at);

-- Refresh function
create or replace function refresh_analytics()
returns void as $$
begin
  refresh materialized view public.orders_analytics;
end;
$$ language plpgsql;

9. 使用触发器进行审计日志记录

-- Audit logs table
create table public.audit_logs (
  id bigint generated always as identity primary key,
  table_name text not null,
  record_id uuid not null,
  action text not null check (action in ('insert', 'update', 'delete')),
  old_data jsonb,
  new_data jsonb,
  user_id uuid references auth.users(id),
  created_at timestamptz default now()
);

-- Trigger function for automatic auditing
create or replace function public.audit_trigger()
returns trigger as $$
begin
  insert into public.audit_logs (
    table_name, record_id, action, old_data, new_data, user_id
  ) values (
    TG_TABLE_NAME,
    coalesce(NEW.id, OLD.id),
    lower(TG_OP),
    to_jsonb(OLD),
    to_jsonb(NEW),
    auth.uid()
  );
  return NEW;
end;
$$ language plpgsql security definer;

10. 使用 pg_notify 的事件驱动模式

-- Publish events using PostgreSQL NOTIFY
create or replace function orders_service.notify_order_created()
returns trigger as $$
begin
  perform pg_notify(
    'order_created',
    json_build_object(
      'order_id', NEW.id,
      'user_id', NEW.user_id,
      'total', NEW.total
    )::text
  );
  return NEW;
end;
$$ language plpgsql;

create trigger order_created_trigger
after insert on orders_service.orders
for each row execute function orders_service.notify_order_created();

核心概念

行级安全（RLS）

PostgreSQL 的一项功能，可根据策略限制用户能够访问的行。对多租户应用和用户数据隔离至关重要。

MCP（Model Context Protocol）

一种使 AI 助手能够与 Supabase 等外部服务交互的协议。它支持自然语言查询和架构操作。Supabase MCP 服务还可通过 Edge Functions 上的 mcp-lite（零冷启动、全球部署）使用，也提供 可自托管的 Docker 镜像（supabase/mcp-server:latest）。

Upsert 模式

使用 onConflict 插入新行，或在行已存在时进行更新。这是一种可防止竞态条件的原子操作。

复合键

跨多个列的唯一约束（例如，session_id,key）。用于在特定上下文中限定数据范围。

JSONB 存储

PostgreSQL 的二进制 JSON 存储格式。在保持查询性能的同时支持灵活的架构。

时态数据

使用 valid_from 和 valid_to 时间戳跟踪历史变更。支持按时间点查询。

服务角色与匿名密钥

• 服务角色：管理员访问权限，可绕过 RLS（仅在服务端使用）
• 匿名密钥：用户访问权限，受 RLS 限制（可安全用于客户端）

参考文件

核心参考资料

references/mcp-setup.md - MCP 服务配置

Supabase MCP 服务设置完整指南：

• 远程（托管）与本地（自托管）安装
• Cursor、Claude Desktop、Claude Code CLI 的配置
• 使用 OAuth 和 Personal Access Tokens 进行身份验证
• 安全最佳实践（只读模式、项目范围限制）
• 连接和身份验证问题排查

references/database-patterns.md - 现代数据库设计

适用于可扩展应用的架构模式：

• 数据湖仓模式（在一个系统中实现 OLTP + OLAP）
• 微服务模式（每个服务使用一个数据库）
• 事件溯源模式（完整审计跟踪）
• CQRS 模式（读写模型分离）
• 继承模式（单表与类表）
• 多态关联
• 时态数据模式（SCD Type 2）

references/schema-design.md - PostgreSQL 最佳实践

健壮的架构设计指南：

• 主键策略（UUID 与 serial）
• 外键关系与级联操作
• 用于查询优化的索引设计
• 约束实施
• 默认值和计算列
• JSON/JSONB 使用模式
• 规范化策略

references/security.md - RLS 与身份验证

生产级安全实现：

• 行级安全策略模式
• 与 auth.users 的身份验证集成
• 基于角色的访问控制（RBAC）
• 数据加密策略
• 审计日志模式
• 多租户安全模型

references/tools-reference.md - MCP 工具

可用 MCP 工具的完整文档：

• 自然语言查询
• 架构内省
• 迁移管理
• 项目配置检索
• 数据库分支（实验性）
• 日志分析和调试

Supabase 官方文档

references/official-docs/row-level-security.md

来自 Supabase 官方文档的完整 RLS 指南：

• 10 种以上的 RLS 策略模式
• 来自真实代码仓库的生产示例
• 常见陷阱及解决方案
• 测试 RLS 策略
• 性能注意事项

references/official-docs/migrations.md

数据库迁移指南：

• 命令式迁移（SQL 文件）
• 声明式架构（schema.yml）
• 迁移工作流和最佳实践
• 处理不兼容变更
• 使用 Supabase 分支进行测试

生产模式

references/production-patterns.md

来自 Twilio-Aldea（生产级 SMS AI 平台）的真实模式：

• 带超时逻辑的会话管理
• 双重持久化（灵魂 + 流程记忆）
• 按区域组织的消息存储
• 带验证的状态管理
• 错误处理和优雅降级
• 加载或创建模式

代码示例

assets/examples/supabase-client.ts

适用于服务端应用的单例模式客户端初始化

assets/examples/session-management.ts

具有自动超时和状态重置功能的会话管理

assets/examples/memory-store.ts

双重持久化模式（灵魂记忆 + 流程记忆）

assets/examples/rls-policies.sql

涵盖常见用例的 10 种生产就绪 RLS 策略模式

GitHub 仓库（新增）

references/github/README.md

来自 GitHub 的官方 Supabase JS 客户端 README（supabase/supabase-js，4,045 颗星）

references/github/issues.md

38 个 GitHub 问题，展示常见问题及解决方案：

• JWT 令牌验证问题
• Next.js 缓存集成
• BigInt ID 处理
• WebSocket 竞态条件
• RLS 标头传递
• Realtime 订阅错误

references/github/CHANGELOG.md

包含不兼容变更和迁移的完整版本历史

references/github/releases.md

410 个 GitHub 发布版本，包含详细的发布说明和迁移指南

references/github/file_structure.md

仓库结构（521 个文件），展示源代码组织方式

使用此技能

初学者

从这里开始：

1. 阅读 references/mcp-setup.md，了解 MCP 的初始配置
2. 查看 assets/examples/supabase-client.ts，了解客户端设置基础知识
3. 学习 references/official-docs/migrations.md，了解架构管理
4. 通过 MCP 练习简单的 CRUD 操作
5. 查看上方的快速参考示例 #1-3

第一个项目：

• 将 MCP 设置为只读模式，以便安全探索
• 创建一个带有 RLS 的简单用户资料表
• 通过 MCP 练习自然语言查询
• 创建你的第一个迁移

中级用户

深入学习：

1. 学习 references/official-docs/row-level-security.md，了解全面的 RLS 模式
2. 查看 assets/examples/rls-policies.sql 中适用于生产环境的策略
3. 使用 assets/examples/session-management.ts 实现会话管理
4. 探索 references/database-patterns.md，了解高级设计
5. 查看上方的快速参考示例 #4-7

实践项目：

• 带有组织、成员和 RLS 的多租户 SaaS 应用
• 使用触发器的审计日志系统
• 带有超时逻辑的基于会话的状态管理
• 时态数据跟踪（产品价格历史）

高级用户

掌握生产环境模式：

1. 学习 references/production-patterns.md，了解实际应用模式
2. 使用 assets/examples/memory-store.ts 实现双重持久化
3. 采用每项服务对应一个数据库的方式设计微服务架构
4. 使用索引策略和查询分析优化性能
5. 查看上方的快速参考示例 #8-10

高级挑战：

• 使用 CQRS 模式实现事件溯源
• 多区域复制与一致性
• 带负载均衡的高可用 MCP 部署
• 带有动态角色分配的复杂 RLS 策略
• 针对百万行表的性能优化

导航提示

查找合适的文档：

• MCP 设置问题？ → references/mcp-setup.md
• 安全/RLS 问题？ → references/official-docs/row-level-security.md 或 references/security.md
• 架构设计决策？ → references/database-patterns.md 或 references/schema-design.md
• 生产环境示例？ → references/production-patterns.md 或 assets/examples/
• 迁移策略？ → references/official-docs/migrations.md

快速查阅： 使用“快速参考示例”部分获取代码片段，无需深入查阅完整文档。

最佳实践总结

数据库设计

1. 从简单开始，逐步演进 - 先进行规范化，再根据使用情况反规范化
2. 将 UUID 用作主键 - 更适合分布式系统，并可防止枚举
3. 谨慎使用 JSONB - 已知字段优先使用类型化列
4. 从第一天起实施 RLS - 将安全性内置其中，而非事后补上
5. 对架构进行版本管理 - 使用迁移进行所有更改

MCP 使用

1. 限定项目范围 - 将访问权限限制在特定项目
2. 启用只读模式 - 用于开发和探索
3. 手动批准工具 - 在生产环境中保持启用
4. 监控 API 使用情况 - 通过仪表板跟踪操作
5. 在分支中测试 - 使用分支测试架构更改

安全

1. 实施 RLS 策略 - 切勿仅依赖应用层安全性
2. 谨慎使用服务角色密钥 - 仅在必要时绕过 RLS
3. 审计所有操作 - 记录数据库管理操作
4. 加密敏感数据 - 使用 PostgreSQL 加密个人身份信息（PII）
5. 定期进行安全审查 - 定期审计 RLS 策略

性能

1. 为外键建立索引 - 始终为连接中使用的列建立索引
2. 使用 EXPLAIN ANALYZE - 了解查询执行计划
3. 避免 N+1 查询 - 使用连接或批量获取
4. 物化视图 - 用于开销较大的分析查询
5. 连接池 - 在高并发场景中使用 pgBouncer

常见工作流

自然语言数据库查询

Ask Claude: "Show me all users who signed up last month but haven't completed their profile"

使用 AI 进行架构设计

Ask Claude: "Design a schema for a multi-tenant SaaS application with organizations, users, and billing"

生成迁移

Ask Claude: "Generate a migration to add a 'status' column to the posts table with an enum type"

RLS 策略创建

Ask Claude: "Create RLS policies so users can only see posts from organizations they're members of"

查询优化

Ask Claude: "Analyze this query and suggest optimizations: SELECT * FROM orders WHERE user_id = '...' AND created_at > '2024-01-01'"

故障排除速查

MCP 连接失败

• 确认 API 密钥正确且未过期
• 检查与 MCP 端点的网络连接
• 确保已正确设置组织权限
• 尝试运行：claude mcp list，查看已配置的服务

RLS 策略错误

• 在不同的用户上下文中测试策略
• 使用 auth.uid() 检查当前用户
• 请记住，服务角色密钥会绕过 RLS
• 使用 EXPLAIN 检查策略：EXPLAIN SELECT * FROM table_name;

迁移失败

• 始终先在分支上测试迁移
• 检查依赖项问题（外键、触发器）
• 在更改架构前确认数据兼容性
• 在本地使用 supabase db reset 从头开始测试

性能问题

• 使用 EXPLAIN ANALYZE 检查查询计划
• 检查外键是否缺少索引
• 监控连接池利用率
• 使用 pg_stat_user_indexes 跟踪索引使用情况

版本历史

• v2.1（2026-04-21）- 更新为通过 mcp-lite Edge Functions 部署（冷启动为零）、通过 Docker 自托管 MCP，并注明仍处于公开 Alpha 阶段
• v2.0（2025-11-01）- 增补官方 Supabase 文档、来自 Twilio-Aldea 的生产实践、TypeScript/SQL 示例，以及全面的 RLS 指南
• v1.0 - 初始版本，包含 MCP 设置、数据库模式、架构设计、安全性和工具参考