supabase-load-scale

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!) // analytics

Then send analytics queries to supabaseReadOnly and all writes to supabase. Replicas lag slightly (typically <100ms), so never read-after-write on a replica. Full client config, pooled psql connection strings, query-routing services, and a pool-usage monitoring query: read replicas and connection pooling.

Step 2 — Compute Upgrades, CDN for Storage, and Edge Function Regions

Match compute tier to traffic (Micro 60 connections → 4XL 480), serve public Storage buckets through the CDN with long cacheControl headers plus content-addressed paths for cache busting, and deploy Edge Functions to the region closest to users:

supabase projects update --experimental --compute-size large   # scale compute
supabase functions deploy my-function --region eu-west-1        # deploy near users

Full compute selection table, CDN upload/transform patterns, versioned-asset cache busting, and the regional geo-router Edge Function: compute, CDN, and edge regions.

Step 3 — Database Table Partitioning

Split large append-heavy tables (events, logs, metrics) by date range so queries scan only the relevant partitions and old data drops cheaply. See table partitioning patterns for range partitioning by date, automated partition creation via pg_cron, SDK query patterns with partition-key filters, and partition drop for data retention.

Output

• Read replica client configured for analytics/dashboard queries, primary for writes
• Connection pooling mode selected (transaction vs session) with correct port
• Compute tier matched to traffic requirements
• Storage uploads optimized with CDN cache headers and image transforms
• Edge Functions deployed to the region closest to users
• Large tables partitioned by date range with automated partition management
• Data retention policy via partition drops

Error Handling

Examples

Quick Connection Pool Check

# Check how many connections are in use right now
psql "$DATABASE_URL" -c "SELECT count(*) AS active_connections FROM pg_stat_activity WHERE state = 'active';"

For deeper worked examples — swapping an existing table to a partitioned one (create/migrate/rename in a transaction) and measuring live read-replica lag — see advanced scaling examples.

Resources

• Supabase Read Replicas
• Supabase Connection Pooling (Supavisor)
• Supabase Compute Add-ons
• Supabase Storage CDN
• Supabase Edge Functions
• PostgreSQL Table Partitioning

Next Steps

For reliability patterns (circuit breakers, offline queues, graceful degradation), see supabase-reliability-patterns.