supabase-load-scale

name	supabase-load-scale
description	Use when preparing a Supabase project for production load — traffic spikes, connection-limit tuning, read replicas for analytics queries, CDN caching for Storage, regional Edge Function deployment, or partitioning large tables. Covers read replicas, Supavisor connection pooling, compute-size upgrades, Storage CDN, Edge Function regions, and table partitioning. Trigger with phrases like "supabase scale", "supabase read replica", "supabase connection pooling", "supabase compute upgrade", "supabase CDN storage", "supabase edge function regions", "supabase partitioning", "supavisor", "supabase pool mode".
allowed-tools	Read, Write, Edit, Bash(supabase:*), Bash(psql:*), Bash(curl:*), Grep
version	1.53.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","supabase","scaling","performance","connection-pooling","read-replicas","partitioning"]
compatibility	Designed for Claude Code

Supabase Load & Scale

Overview

Supabase scaling operates at six layers: read replicas (offload analytics and reporting queries), connection pooling (Supavisor, the pgBouncer replacement, with transaction/session modes), compute upgrades (vCPU/RAM tiers), CDN for Storage (cache public bucket assets at the edge), Edge Function regions (deploy functions closer to users), and table partitioning (split billion-row tables for query performance). This skill gives the high-level workflow inline and links to references/ for the full createClient config, SQL, and CLI for each layer.

Prerequisites

• Supabase project on a Pro plan or higher (read replicas require Pro+)
• @supabase/supabase-js v2+ installed
• supabase CLI installed and linked to your project
• Database access via psql or Supabase SQL Editor
• TypeScript project with generated database types

Instructions

Step 1 — Read Replicas and Connection Pooling

Route read-heavy queries (dashboards, reports, search) to a read replica while keeping writes on the primary. Supavisor pools connections in two modes: transaction (default, port 6543 — shares connections, no prepared statements) and session (port 5432 — one connection per client, needed for prepared statements and LISTEN/NOTIFY). Configure two clients — a primary and a read-only replica pointed at the -ro URL:

// lib/supabase.ts
export const supabase = createClient<Database>(
  process.env.SUPABASE_URL!, process.env.SUPABASE_ANON_KEY!)       // writes + realtime
export const supabaseReadOnly = createClient<Database>(
  process.env.SUPABASE_READ_REPLICA_URL!, process.env.SUPABASE_ANON_KEY!)