Realtime messages

When to use each feature

Prerequisites

Before you begin, ensure that you have:

• An RDS Supabase project

• The supabase-js client library installed

• Realtime enabled on any tables you want to monitor (required for Postgres Changes)

Postgres Changes

Postgres Changes lets clients subscribe to INSERT, UPDATE, and DELETE operations on database tables, receiving changes in real time via PostgreSQL logical replication.

Monitored tables must have a primary key. Enable Realtime for the target table in your RDS Supabase project before using this feature.

The following example subscribes to INSERT events on the public.messages table:

const channel = supabase
  .channel('db-changes')
  .on('postgres_changes', {
    event: 'INSERT',
    schema: 'public',
    table: 'messages'
  }, (payload) => {
    console.log('New message:', payload.new);
  })
  .subscribe();

Broadcast

Broadcast sends low-latency messages between connected clients. Use it for chat, notifications, and similar use cases. Messages are delivered only to currently connected clients and are not persisted.

Push a message with channel.send() and receive it by listening for the broadcast event. This pattern supports both point-to-point and group communication.

1. Create a channel with Broadcast enabled:

   const channel = supabase.channel('chat-room', {
     config: {
       broadcast: { self: false },
       presence: false
     }
   });

2. Send a broadcast message:

   await channel.send({
     type: 'broadcast',
     event: 'message',
     payload: { text: 'Hello' }
   });

Presence

Presence tracks the online status of users in a channel — for example, online, away, or typing. After joining a channel, call track() to register a client's status. Retrieve the current list of online users with channel.presenceState().

const channel = supabase.channel('room:lobby', {
  config: { presence: { key: 'user1' } }
});

channel.subscribe(async (status) => {
  if (status === 'SUBSCRIBED') {
    await channel.track({
      online_at: new Date().toISOString(),
      state: 'online'
    });
  }
});

References

For more information about Supabase Realtime, see the Realtime documentation.