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+ installedsupabase 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:
export const supabase = createClient<Database>(
process.env.SUPABASE_URL!, process.env.SUPABASE_ANON_KEY!)
export const supabaseReadOnly = createClient<Database>(
process.env.SUPABASE_READ_REPLICA_URL!, process.env.SUPABASE_ANON_KEY!)
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
supabase functions deploy my-function --region eu-west-1
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
| Issue | Cause | Solution |
|---|
too many connections for role | Exceeded Supavisor pool limit | Use transaction mode (port 6543), reduce idle connections, upgrade compute |
| Read replica returns stale data | Replication lag (typically <100ms) | Do not read-after-write on replica; use primary for consistency-critical reads |
no partition of relation "events" found for row | Insert date outside any partition range | Create a DEFAULT partition or pre-create future partitions |
| Storage CDN returns old file | Cached at edge | Use content-addressed paths (hash.ext) or set shorter cacheControl |
| Edge Function cold start | First request to a region | Use keep-alive cron ping or accept ~200ms cold start |
prepared statement already exists | Transaction mode doesn't support prepared statements | Switch to session mode (port 5432) or disable prepared statements in your ORM |
Examples
Quick Connection Pool Check
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
Next Steps
For reliability patterns (circuit breakers, offline queues, graceful degradation), see supabase-reliability-patterns.
