supabase-reliability-patterns

name	supabase-reliability-patterns
description	Build resilient Supabase integrations: circuit breakers wrapping createClient calls, offline queue with IndexedDB, graceful degradation with cached fallbacks, health check endpoints, retry with exponential backoff and jitter, and dual-write patterns for critical data. Use when building fault-tolerant apps, handling Supabase outages gracefully, implementing offline-first patterns, or adding retry logic to SDK calls. Trigger with phrases like "supabase circuit breaker", "supabase offline", "supabase retry", "supabase health check", "supabase fallback", "supabase resilience", "supabase dual write", "supabase outage".
allowed-tools	Read, Write, Edit, Bash(supabase:*), Bash(curl:*), Grep
version	1.53.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","supabase","reliability","resilience","circuit-breaker","offline","retry"]
compatibility	Designed for Claude Code

Supabase Reliability Patterns

Overview

Production Supabase apps need six reliability layers: circuit breakers (stop calling Supabase when it's down to prevent cascading failures), offline queue (buffer writes when the network is unavailable and replay when reconnected), graceful degradation (serve cached or fallback data during outages), health checks (detect Supabase availability before routing traffic), retry with exponential backoff (handle transient errors without overwhelming the service), and dual-write (write critical data to both Supabase and a backup store). All patterns use real createClient from @supabase/supabase-js.

Prerequisites

• @supabase/supabase-js v2+ installed
• TypeScript project with Supabase client configured
• For offline queue: browser environment with IndexedDB or server with Redis
• For dual-write: secondary data store (Redis, DynamoDB, or local SQLite)

Instructions

Step 1 — Circuit Breaker and Retry with Exponential Backoff

A circuit breaker tracks failures per Supabase service (database, auth, storage) and stops making calls when a threshold is exceeded. Combined with retry logic, it prevents both cascading failures and unnecessary retries during extended outages.

Circuit Breaker Implementation

// lib/circuit-breaker.ts
import { createClient } from '@supabase/supabase-js'
import type { Database } from './database.types'

type CircuitState = 'CLOSED' | 'OPEN' | 'HALF_OPEN'

interface CircuitBreakerOptions {
  failureThreshold: number    // failures before opening
  resetTimeoutMs: number      // ms before trying again (half-open)
  :    
  :                 
}

  {
   :  = 
   failures = 
   lastFailureTime = 
   halfOpenSuccesses = 

  () {}

   call<T>(:  <T>, ?:  T): <T> {
    
     (. === ) {
       (.() - . > ..) {
        . = 
        . = 
        .()
      }  {
         (fallback)  ()
          ()
      }
    }

     {
       result =  ()

      
       (. === ) {
        .++
         (. >= ..) {
          . = 
          . = 
          .()
        }
      }  {
        . =   
      }

       result
    }  (error) {
      .++
      . = .()

       (. >= ..) {
        . = 
        .(
          
        )
      }

       (fallback)  ()
       error
    }
  }

   () {
     { : ., : . }
  }
}


  dbCircuit =  ({
  : ,
  : ,
  : ,
  : ,
})

  authCircuit =  ({
  : ,
  : ,
  : ,
  : ,
})

  storageCircuit =  ({
  : ,
  : ,
  : ,
  : ,
})