Supabase Realtime - AI-Optimized Technical Reference

Configuration That Actually Works in Production

Database Changes (Postgres Changes)

• Purpose: Stream INSERT, UPDATE, DELETE events from database
• Latency: 100-500ms (WAL replication dependent)
• Reliability: Most reliable but slowest option
• Setup Requirements:

  ALTER PUBLICATION supabase_realtime ADD TABLE messages;
  

• Production Configuration:

  const channel = supabase.channel('messages-changes', {
    config: {
      heartbeat_timeout: 60000,  // Override 30s default
      reconnect_after_timeout: 5000
    }
  })
  

Broadcast Messages

• Purpose: Ephemeral real-time messaging between clients
• Latency: <50ms (ideal), 500ms+ during congestion
• Message Limit: 256KB per message
• Delivery: Best-effort (no guarantees)
• Critical Implementation:

  // Add timestamp handling for message ordering
  payload: { 
    data: content, 
    timestamp: Date.now(),
    sequence: messageId++
  }
  

Presence Tracking

• Purpose: Track user state using CRDTs
• Latency: <50ms
• State Limit: 64KB per presence
• Consistency: Eventually consistent (ghost users accumulate)

Critical Failure Modes

Connection Pool Death Spiral

• Symptom: WebSocket connections timeout during traffic spikes
• Impact: Complete service unavailability
• Resolution: Restart entire service stack
• Prevention: Implement connection limits and backpressure

WAL Replication Lag Hell

• Trigger: Database under heavy write load
• Impact: "Real-time" becomes "eventual-time"
• Performance Threshold: Replication lag >1000ms makes system unusable
• Mitigation: Batch operations, monitor replication slot lag

Message Ordering Chaos

• Cause: Network congestion, no built-in sequencing
• Impact: Collaborative features break (cursors jump randomly)
• Required Solution: Client-side timestamp handling and message sequencing
• Implementation Cost: Additional 20-30% development time

Phantom Presence Problem

• Cause: Force-quit browsers, WiFi disconnections
• Impact: Ghost users accumulate indefinitely
• Consequence: User lists become meaningless over time
• Solution: Custom heartbeat system (not built-in)

Regional Routing Madness

• Expected: 50ms Singapore-US latency
• Reality: 500ms when AWS routing breaks
• Debugging Capability: Zero (black box routing)
• Business Impact: User experience degrades unpredictably

Resource Requirements

Time Investment

• Basic Implementation: 2-3 days
• Production-Ready: 2-3 weeks (debugging edge cases)
• Message Ordering System: Additional 1 week
• Ghost User Cleanup: Additional 3-5 days

Expertise Requirements

• WebSocket Connection Management: Advanced
• Distributed Systems Debugging: Expert level
• PostgreSQL Replication: Intermediate
• Client-Side State Management: Advanced

Billing Traps

• Rate: $2.50 per million messages
• Cursor Movement Reality: 100+ messages/second per user
• Example Cost: 20 users, whiteboard app = $120/week for cursors alone
• Hidden Costs: Heartbeats, reconnection attempts, presence updates all count
• Mitigation: Aggressive rate limiting required

Decision Criteria

When Supabase Realtime Works

• Chat applications: Good for text messages (handle out-of-order delivery)
• Live dashboards: Acceptable for non-critical data updates
• Notifications: Reliable when backed by database storage
• User limit: <100 concurrent users per channel

When to Choose Alternatives

• Financial applications: Never (no delivery guarantees)
• Collaborative editing: Too many message ordering issues
• High-frequency updates: Billing becomes prohibitive
• >1000 concurrent users: Performance degrades significantly

Breaking Points

• Database: WAL replication fails at >500 writes/second
• UI Performance: Breaks at 1000+ UI spans (debugging impossible)
• Message Volume: >10 million messages/month = $25+ just in Realtime costs
• Connection Count: 16,384 WebSocket limit per node

Production Warnings

What Documentation Doesn't Tell You

• Default timeouts will fail: 30s connection timeout appears broken to users
• RLS changes break silently: Recent versions enforce authorization differently
• WAL replication stops randomly: Postgres 15+ issue during high throughput
• Mobile browsers kill connections: Aggressive background tab management

Required Defensive Code Patterns

// Essential error handling
channel
  .on('error', (error) => {
    // Connection died, implement resurrection logic
    handleRealtimeFailure(error)
  })
  .on('disconnect', (reason) => {
    // Mobile browsers, WiFi, corporate firewalls
    scheduleReconnection(reason)
  })

// Message ordering for broadcasts
const messageQueue = new Map()
function processMessage(payload) {
  if (payload.timestamp < lastProcessed[payload.user_id]) {
    return // Ignore out-of-order message
  }
  // Process message
}

// Rate limiting to prevent billing explosion
const rateLimiter = new RateLimiter({
  tokensPerInterval: 10,
  interval: 1000
})

Migration Pain Points

• No migration guides: Version changes break existing code silently
• Authorization changes: August 2024 update requires code changes
• Client library incompatibilities: Each platform has unique breaking changes
• Database requirements: Managed DB providers often restrict logical replication

Performance Thresholds

Metric	Acceptable	Degraded	Broken
Connection Latency	<100ms	100-500ms	>500ms
WAL Replication Lag	<500ms	500ms-2s	>2s
Message Delivery	<50ms	50-200ms	>200ms
Concurrent Users	<100	100-500	>500
Messages/Hour	<100K	100K-1M	>1M

Community and Support Quality

• Discord Community: Responsive for urgent issues (3AM debugging)
• GitHub Issues: Active tracking of real production bugs
• Documentation: Marketing-heavy, light on production gotchas
• Enterprise Support: Available but expensive
• Community Libraries: Python/Swift clients are community-maintained (variable quality)

This system works great in demos but requires significant defensive programming for production use. Budget 3x normal development time for proper error handling and edge case management.