name: supabase-realtime-publication-debug

description: "Debug Supabase Realtime: frontend subscribes but never receives updates. Root cause: table not in supabase_realtime publication."

category: supabase

tags: [supabase, realtime, postgres, publication, websocket]

Supabase Realtime — Tabela Não Recebe Updates Despite Subscription

Symptom

Frontend has Supabase realtime subscription configured:

`typescript

supabase.channel('all-realtime')

.on('postgres_changes', { event: 'UPDATE', schema: 'public', table: 'tasks' }, handler)

.subscribe()

`

The subscription connects fine, but UPDATE/INSERT/DELETE events from the database never reach the frontend. No errors, no indication of what's wrong.

Root Cause

Supabase Realtime requires explicit inclusion of each table in the supabase_realtime PostgreSQL publication. This is NOT automatic — it's a separate publication layer that the Supabase Dashboard's Replication UI manages, but if a table is missing from the publication, realtime events are silently dropped.

Diagnostic SQL

Run on the Supabase Postgres database (via psql or Docker exec):

`sql

-- Check which tables are in the supabase_realtime publication

SELECT tablename

FROM pg_publication_tables

WHERE pubname = 'supabase_realtime';

-- Check if a specific table is missing

SELECT count(*)

FROM pg_publication_tables

WHERE pubname = 'supabase_realtime' AND tablename = 'tasks';

-- Returns 0 = table is NOT in the publication (problem!)

-- Returns 1 = table is in the publication (OK)

`

Fix

`sql

-- Add the missing table to the publication

ALTER PUBLICATION supabase_realtime ADD TABLE tasks;

`

To add ALL tables at once (useful after migrations create new tables):

`sql

-- Add specific tables

ALTER PUBLICATION supabase_realtime ADD TABLE tasks;

ALTER PUBLICATION supabase_realtime ADD TABLE message_log;

ALTER PUBLICATION supabase_realtime ADD TABLE message_replies;

ALTER PUBLICATION supabase_realtime ADD TABLE incoming_messages;

`

How to Run on VPS

`bash

Docker-based Supabase Postgres

docker exec deploy-vps-db-1 psql -U postgres -d postgres -c "ALTER PUBLICATION supabase_realtime ADD TABLE tasks;"

List tables currently in publication

docker exec deploy-vps-db-1 psql -U postgres -d postgres -t -c "SELECT tablename FROM pg_publication_tables WHERE pubname = 'supabase_realtime';"

`

Verify After Fix

`sql

-- Should return 1 for each table you expect to use realtime

SELECT tablename FROM pg_publication_tables WHERE pubname = 'supabase_realtime';

`

Gotchas

• - Supabase Dashboard UI: The Database Replication tab in Supabase Studio shows which tables are in the publication. But after adding a table via SQL, the Dashboard may not refresh immediately — verify with the SQL query above.
• - New tables after this fix: Any new table created by migrations will also need to be added to the publication separately.
• - supabase-js SDK vs raw WebSocket: The SDK handles reconnection automatically. If you restart the container, the subscription reconnects. No code change needed.
• - RLS policies still apply: Realtime still respects RLS. If a user does not have SELECT permission on a row, they will not see the realtime event for that row.

Context

This issue is particularly insidious because:

1. The frontend subscription code looks correct

2. No errors are thrown — events are silently discarded

3. The Supabase Dashboard may show the subscription as connected

4. Regular CRUD via PostgREST/REST API works fine — only realtime is broken

Pattern: This commonly happens after:

• - A new table is created via migration
• - A table is renamed or recreated
• - The realtime publication is reset during a Supabase upgrade
• - Adding realtime to an existing project that predates the realtime feature