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

TL;DR: Create one channel per concern with a descriptive topic, for example per chat room or per dashboard widget. # Supabase Realtime channels: subscribe narrowly and clean up Realtime is easy to start and easy to misuse. The failure modes agents hit: subscribing to

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.

When to use

You hit exactly this: Supabase Realtime channel setup: subscribe with filters, or every client gets every event in Supabase Realtime channel setup.

When not to use

A different error, or the same symptom in a different tool. This page only covers the failure above.

Compatibility

Supabase Realtime channel setup.

Edge cases

• with explicit.
• Filters that do not match this syntax silently match nothing.
• For high-frequency updates, prefer.
• for ephemeral messages and reserve.
• for database state.

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