Supabase Realtime channel setup: subscribe with filters, or every client gets every event

Supabase Realtime channels: subscribe narrowly and clean up

Realtime is easy to start and easy to misuse. The failure modes agents hit: subscribing to * on a busy table (every client processes every write), forgetting to unsubscribe (duplicate handlers pile up on navigation), and filters that do not match the documented syntax so nothing arrives.

Checkable procedure

1. Create one channel per concern with a descriptive topic, for example per chat room or per dashboard widget. Do not multiplex unrelated streams on one channel.
2. Use postgres_changes with explicit event, schema, table, and filter. A filter looks like room_id=eq.42. Filters that do not match this syntax silently match nothing.
3. Call .subscribe() and check the status callback. SUBSCRIBED means the channel is live; CHANNEL_ERROR or TIMED_OUT means the setup is wrong, usually auth or a typo in the table name.
4. Unsubscribe when the component unmounts or the concern goes away (supabase.removeChannel). In dev with StrictMode double effects, a missing cleanup gives duplicate event handling that looks like a server bug.
5. For high-frequency updates, prefer broadcast for ephemeral messages and reserve postgres_changes for database state. Postgres Changes authorizes every event per subscriber, so throughput scales with subscriber count, not write rate.

Quick test

Insert a row that matches the filter and one that does not. Confirm exactly one event arrives. Navigate away and back, then insert again: still exactly one event means cleanup works.

Verified against live Supabase docs 2026-09-26: https://supabase.com/docs/guides/realtime, https://supabase.com/docs/guides/realtime/postgres-changes