realtime/overview

40 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Realtime application examples

Supabase Realtime can be used to build chat applications with real-time messaging, typing indicators, and online presence; collaborative tools like document editing, whiteboards, and shared workspaces; live dashboards for real-time data visualization and monitoring; multiplayer games with synchronized game state and player interactions; and social features including live notifications, reactions, and user activity feeds.

Supabase Realtime core features

Supabase Realtime is a globally distributed service that provides three main features: Broadcast for sending low-latency messages between clients, Presence for tracking and synchronizing user state across clients, and Postgres Changes for listening to database changes in real-time.

Realtime authentication performance: 50,000 concurrent users

With Authentication Row Level Security (RLS) enabled on broadcast channels, the system achieved 50,000 concurrent users with 100,000 total channel joins (100 users per channel), >150,000 msgs/sec throughput, 500 conn/sec new connection rate, and 1000 joins/sec channel join rate. Median latency was 19 ms, p95 was 49 ms, and p99 was 96 ms.

Production performance variability

Performance in production environments may vary based on factors such as network conditions, hardware specifications, and specific usage patterns.

Benchmark testing methodology

Benchmarks are conducted using k6 load testing tool against a Realtime Cluster deployed on AWS with 2-6 nodes in single-region and multi-region setups. Load generators are deployed on AWS to minimize network latency. Tests execute with full load from start without warm-up runs. Metrics include message throughput, latency percentiles, CPU and memory utilization, and connection success rates.

Initialize Supabase client with project URL and key

Create a Supabase client using createClient() in TypeScript with the project URL (https://<project>.supabase.co) and publishable key (sb_publishable_key). The client is initialized once and used for all Realtime operations.

Install Supabase client library

The @supabase/supabase-js package is installed via npm install @supabase/supabase-js for TypeScript. Other SDKs are available: flutter pub add supabase_flutter for Flutter, supabase-swift from GitHub for Swift, pip install supabase for Python, and dotnet add package Supabase for C#.

Realtime limits by plan - channel joins per second

Channel joins per second limits are: Free 100, Pro 500, Pro (no spend cap) 2,500, Team 2,500, Enterprise 2,500+.

Realtime tenant_events error and reconnection

The tenant_events error occurs when a project generates too many messages per second, causing connections to be disconnected. The supabase-js client will reconnect automatically when message throughput decreases below the plan limit. An event is a WebSocket message delivered to or sent from a client.

Realtime too_many_connections error

The too_many_connections error is a WebSocket message sent when too many total concurrent connections exist for a project.

Realtime too_many_joins error

The too_many_joins error is a WebSocket message sent when too many channel joins per second are attempted.

Realtime too_many_channels error

The too_many_channels error is a WebSocket message sent when too many channels are currently joined for a single connection.

Realtime limits by plan - concurrent connections

Concurrent connections limits are: Free 200, Pro 500, Pro (no spend cap) 10,000, Team 10,000, Enterprise 10,000+.

Realtime limits by plan - channels per connection

Channels per connection limits are: Free 100, Pro 100, Pro (no spend cap) 100, Team 100, Enterprise 100+.

Realtime messages charge

Realtime billing includes a charge for the number of Realtime messages. Detailed explanation of how charges are calculated can be found in the Manage Realtime Messages usage documentation.

Realtime peak connections charge

Realtime billing includes a charge for the number of Realtime peak connections. Detailed explanation of how charges are calculated can be found in the Manage Realtime Peak Connections usage documentation.

Realtime billing based on messages and peak connections

Supabase Realtime charges are based on two metrics: the number of Realtime messages and the number of Realtime peak connections.

Realtime with Next.js guide overview

Supabase provides a guide for using Realtime with Next.js that covers client and server side updates for receiving real-time Postgres changes. The guide explores which approach is best for different use cases.

Realtime Settings overview

Realtime Settings are configured in the Dashboard and allow you to control how Realtime operates for your project. All changes made in the settings screen will disconnect all connected clients to ensure Realtime starts with the appropriate settings and all changes are stored in Supabase middleware.

Enable Realtime service setting

The 'Enable Realtime service' setting determines if the Realtime service is enabled or disabled for your project.

Max concurrent clients setting

The 'Max concurrent clients' setting determines the maximum number of clients that can be connected to Realtime.

Max payload size in KB setting

The 'Max payload size in KB' setting determines the maximum payload size in KB that can be sent through Realtime.

Two methods for real-time database changes

Supabase provides two options for subscribing to real-time database changes: Broadcast (recommended for scalability and security) and Postgres Changes (simpler method that requires less setup but does not scale as well).

Message Payload Size report

The Message Payload Size report monitors the median size of message payloads sent through Realtime channels over time. Payload size directly affects message throughput and latency—larger payloads require more bandwidth and processing time, which can increase latency and reduce the number of messages the system can handle per second. Monitoring this metric helps optimize message structure and identify opportunities to reduce payload sizes for better performance. Available for all plans.

Realtime Reports overview table

Realtime reports provide insights into connections, broadcast and change events, execution times, and lag. The following reports are available: Connected Clients (all plans) shows total connected clients; Broadcast Events (all plans) shows broadcast events sent by clients; Presence Events (all plans) shows presence events sent by clients; Postgres Changes Events (all plans) shows Postgres changes events received by clients; Rate of Channel Joins (all plans) shows rate of change of users joining channels; Message Payload Size (all plans) shows median size of message payloads sent; Broadcast from Database Replication Lag (Pro, Team, Enterprise) shows time from database change to broadcast to clients; (Read) Private Channel Subscription RLS Execution Time (Pro, Team, Enterprise) shows RLS policy impact on time to validate if user can join private channel; (Write) Private Channel Subscription RLS Execution Time (Pro, Team, Enterprise) shows RLS policy impact on time to validate if user can write to private channel; Total Requests (all plans) shows total requests to Realtime API; Response Errors (all plans) shows response errors from Realtime API; Response Speed (all plans) shows average response time from Realtime API.

Connected Clients report

The Connected Clients report monitors the total number of concurrent Realtime client connections over time. Each client connection represents an active WebSocket connection to Realtime service, which can subscribe to multiple channels. This metric is essential for understanding connection usage patterns and identifying when approaching connection limits. Available for all plans.

Connection limits by plan

Connection limits vary by plan: Free plan has 200 connections, Pro plan has 500 connections, Pro no spend cap has 10,000 connections, Team plan has 10,000 connections, and Enterprise plan has 10,000+ connections.

Total Requests report

The Total Requests report helps monitor the overall volume of HTTP requests for Realtime over time. The report displays the total number of HTTP requests made to the Realtime service which include WebSocket upgrade requests and REST API requests. Essential for understanding application usage patterns and identifying traffic trends or potential issues with API request handling. Available for all plans.

Response Errors report

The Response Errors report helps monitor the number of failed HTTP requests to the Realtime service over time. These errors include HTTP error status codes (4xx client errors and 5xx server errors) from REST API requests, failed WebSocket upgrade requests, authorization failures, and other error responses. Monitoring error rates alongside total requests helps identify patterns, correlate errors with specific events, and troubleshoot issues affecting Realtime service availability. Available for all plans.

Response Speed report

The Response Speed report helps monitor the average response time for HTTP requests to the Realtime service over time. The report displays the average response time in milliseconds, showing how fast the Realtime service responds to HTTP requests throughout the selected time period. This includes response times for REST API requests such as broadcast messages, WebSocket upgrade requests, and other HTTP-based interactions. Higher response times can indicate performance bottlenecks, database load issues, or network problems. Available for all plans.

Realtime Reports access location

Access Realtime reports from Project Settings > Product Reports > Realtime in the project dashboard.

Realtime reports help with monitoring and debugging

Realtime reports help you monitor connection counts and message volumes against plan quotas, identify performance bottlenecks in RLS policies or database replication, troubleshoot errors and connection issues, and plan capacity upgrades based on usage trends.

WebSocket connection URLs for Realtime

For Supabase projects, the WebSocket URL is `wss://<PROJECT_REF>.supabase.co/realtime/v1/websocket?apikey=<API_KEY>`. For self-hosted projects, the URL is `wss://<HOST>:<PORT>/socket/websocket?apikey=<API_KEY>`. URL parameters include `vsn` to set protocol version (possible values: `1.0.0` and `2.0.0`, defaults to `1.0.0`) and `log_level` to set server-side logging for debugging.

Protocol versions: 1.0.0 vs 2.0.0

Protocol version 1.0.0 uses JSON serialization with text-only WebSocket frames and named fields: event, topic, payload, ref, join_ref. Protocol version 2.0.0 uses text frames as JSON arrays with fixed element order [join_ref, ref, topic, event, payload] and also supports binary frames for broadcast messages (types 3 and 4).

Client sent events and their requirements

Client events: phx_join (requires ref and join_ref), phx_leave (requires ref and join_ref), heartbeat (requires ref, no join_ref), access_token (requires ref and join_ref), broadcast (requires ref and join_ref), presence (requires ref and join_ref).

Heartbeat message requirements

Heartbeat messages should be sent at least every 25 seconds to avoid connection timeout. The topic used is `phoenix` (a special topic not connected to any specific channel). Payload should be an empty object. The heartbeat requires a ref but not a join_ref.

Server sent events overview

Server events: phx_close (requires ref and join_ref), phx_error (requires ref and join_ref), phx_reply (requires ref, join_ref marked with *), system (no ref/join_ref), broadcast (no ref/join_ref), presence_state (no ref/join_ref), presence_diff (no ref/join_ref), postgres_changes (no ref/join_ref).

phx_reply event response structure

phx_reply contains: `status` (ok or error) and `response` (varies by event). For phx_join replies, response includes `postgres_changes` array where each object has `id` (unique identifier), `event` (INSERT|UPDATE|DELETE|*), `schema`, and `table`.

Reconnection and phx_error handling

phx_error (unexpected server-side channel process termination) should trigger rejoin with exponential backoff. JS client uses [1000, 2000, 5000, 10000] ms (capped at 10s), configurable via reconnectAfterMs. phx_close after rate-limit system error requires throttling before rejoin. After token system error, refresh token first. phx_close with no preceding system error is clean close - only rejoin if unexpected.

Error handling channels and sources

Errors arrive on four channels: WebSocket close frame before channel joins, phx_reply with status 'error' rejecting phx_join or push, system event on live channel (channel-level errors followed by phx_close, postgres_changes errors are informational and leave channel open), phx_error on unexpected channel process termination.

Give your agent this brain