Supabase Knowledge Patch Skill

Supabase Knowledge Patch

Claude's baseline knowledge covers Supabase through mid-2025. This skill provides features and breaking changes from late 2025 onwards.

Index

references/auth.md — OAuth 2.1 server, custom/Web3 providers, JWT signing keys, before-user-created hook
references/edge-functions.md — Background tasks (waitUntil), S3 mounts, ephemeral storage, getClaims() auth pattern, limits
references/realtime.md — Private channels with RLS, broadcast from database, broadcast replay
references/storage.md — Vector buckets (similarity search), analytics buckets (Iceberg)
references/api-postgrest.md — Publishable/secret API keys, overrideTypes<>(), JSON field inference, Python type gen
references/js-client.md — Node 20+ required, new filters, auth throw mode, skipAutoInitialize, CORS headers export
references/queues-cron.md — Sub-minute pg_cron, pgmq_public queues via PostgREST
references/local-dev.md — Declarative schemas, storage bucket seeding, seed splitting, local backup restore
references/self-hosting.md — Asymmetric keys, Supavisor pooler, reverse proxy overlays, migration guide
references/deployment.md — Branch config, secret management (env()/encrypted:), deployment DAG, CLI commands
references/mcp-server.md — Remote hosted MCP, feature groups, AI SDK integration, PostgREST MCP
references/breaking-changes.md — OpenAPI spec restricted, pg_graphql disabled, Edge Functions rate limits

Quick Reference: New API Key Model

| Type | Format | Replaces | Notes | |------|--------|----------|-------| | Publishable | sb_publishable_... | anon JWT | Safe for client-side | | Secret | sb_secret_... | service_role JWT | Browser-blocked (401) |

Both old and new keys work simultaneously. Not JWTs — gateway mints short-lived JWT internally. Platform-only (not CLI/self-hosted).

// Client-side
const supabase = createClient(SUPABASE_URL, 'sb_publishable_...')
// Server-side
const supabase = createClient(SUPABASE_URL, 'sb_secret_...', {
  auth: { persistSession: false },
})

Quick Reference: Auth

| Feature | API | |---------|-----| | OAuth 2.1 server | supabase.auth.oauth.approveAuthorization(id) | | Custom OAuth/OIDC | supabase.auth.admin.customProviders.createProvider({...}) | | Web3 (Ethereum/Solana) | supabase.auth.signInWithWeb3({ chain: 'ethereum' }) | | JWT claims in Edge Fn | supabase.auth.getClaims(token) | | Throw on error | createClient(url, key, { auth: { throwOnError: true } }) | | Skip auto-init (SSR) | createClient(url, key, { auth: { skipAutoInitialize: true } }) | | Before user hook | SQL function returning { "error": {...} } to reject signup |

OAuth tokens include client_id claim — use in RLS to restrict OAuth client access:

CREATE POLICY "No OAuth access" ON sensitive_table FOR ALL USING (
  auth.uid () = user_id
  AND (auth.jwt () ->> 'client_id') IS NULL
);

Quick Reference: Edge Functions

| Feature | Usage | |---------|-------| | Background tasks | EdgeRuntime.waitUntil(promise) | | S3 mount read/write | Deno.readFile('/s3/BUCKET/path') | | Ephemeral /tmp | 256MB free, 512MB paid; sync APIs only at top level | | Wall clock | 150s free / 400s paid | | CPU per request | 2s | | Bundle size | 20MB | | Functions/project | 100 free / 500 pro / 1000 team |

Quick Reference: Realtime

Private channels require RLS on realtime.messages + private: true:

await supabase.realtime.setAuth()
const channel = supabase.channel('room:123', { config: { private: true } })

Server-side broadcast: SELECT realtime.send(payload, event, topic, private).

Broadcast replay (alpha, private channels only):

const channel = supabase.channel('room:main', {
  config: { private: true, broadcast: { replay: { since: timestamp, limit: 10 } } },
})

Quick Reference: Vector Buckets (Alpha)

const bucket = supabase.storage.vectors.from('embeddings');
await bucket.createIndex({
  indexName: 'docs',
  dataType: 'float32',
  dimension: 1536,
  distanceMetric: 'cosine',
});

const index = bucket.index('docs');
await index.putVectors({
  vectors: [
    { key: 'doc-1', data: { float32: embedding }, metadata: { title: 'Doc' } },
  ],
});
const { data } = await index.queryVectors({
  queryVector: { float32: query },
  topK: 10,
  filter: { category: 'guide' },
});

SQL access via FDW: WHERE data <==> '[...]'::embd ORDER BY embd_distance(data). Limits: 10 buckets, 10 indexes/bucket, 4096 dims.

Quick Reference: Declarative Schemas

Place desired-state SQL in supabase/schemas/, then diff to generate migrations:

supabase db diff -f create_employees_table

[db.migrations]
schema_paths = ["./schemas/employees.sql", "./schemas/*.sql"]

Quick Reference: Secret Management

# env() — reference env vars in any config field
[auth.external.github]
client_id = "env(GITHUB_CLIENT_ID)"
secret = "env(GITHUB_SECRET)"

supabase secrets set --env-file ./supabase/.env

Quick Reference: Queues (pgmq_public)

// Send
await supabase.schema('pgmq_public').rpc('send', {
  queue_name: 'my_queue',
  message: { hello: 'world' },
  sleep_seconds: 0,
});
// Read (with visibility timeout)
await supabase.schema('pgmq_public').rpc('read', {
  queue_name: 'my_queue',
  sleep_seconds: 30,
  n: 5,
});
// Pop (read + delete)
await supabase.schema('pgmq_public').rpc('pop', { queue_name: 'my_queue' });

Requires: enable pgmq extension, toggle "Expose Queues via PostgREST", enable RLS on pgmq.q_<name>.

Quick Reference: JS Client (v2.74–v2.101)

| Change | Version | Details | |--------|---------|---------| | Node.js 20+ required | v2.79.0+ | @supabase/node-fetch removed; pin v2.78.0 for Node 18 | | notin() filter | — | .notin('id', [1,2,3]) | | isdistinct() filter | — | .isdistinct('deleted_at', null) — NULL-safe | | overrideTypes<>() | v2.48.0+ | Override query result types | | Auth throw mode | v2.79.0+ | { auth: { throwOnError: true } } | | detectSessionInUrl fn | v2.88.0+ | Accepts predicate function | | Functions timeout | v2.81.0+ | signal: AbortSignal.timeout(30000) | | CORS headers | v2.95.0+ | import { corsHeaders } from '@supabase/supabase-js/cors' | | DatabaseWithoutInternals | v2.89.0+ | Strips internal schemas from Database type |

Quick Reference: MCP Server

Remote: https://mcp.supabase.com/mcp (HTTP transport, OAuth 2.1 auth). Local CLI: http://localhost:54321/mcp (no OAuth).

Config via URL params: ?project_ref=...&read_only=true&features=database,docs

Feature groups: account, docs, database, debugging, development, functions, storage, branching. All enabled by default except storage.

Quick Reference: Sub-Minute Cron

SELECT cron.schedule('fast-poll', '30 seconds', 'SELECT process_pending()');

Valid: 1–59 seconds. Requires Postgres 15.1.1.61+.

Breaking Changes (2025–2026)

OpenAPI spec via anon key removed (Mar 2026) — use service_role or sb_secret_ key
pg_graphql disabled by default on new projects — CREATE EXTENSION pg_graphql to re-enable
PostgREST v14 JWT cache — enabled by default (~20% more RPS); disable: ALTER ROLE authenticator SET pgrst.jwt_cache_max_entries TO 0
Edge Functions recursive call rate limit (Mar 2026) — 5,000 req/min budget for function-to-function calls within a project

Agent Skills: Supabase Knowledge Patch

Install this agent skill to your local

Skill Files