Realtime Concepts

Learn about Channels and other extensions in Supabase Realtime

You can use Supabase Realtime to build real-time applications with collaborative/multiplayer functionality. It includes 3 core extensions:

• Broadcast: sends rapid, ephemeral messages to other connected clients. You can use it to track mouse movements, for example.
• Presence: sends user state between connected clients. You can use it to show an "online" status, which disappears when a user is disconnected.
• Postgres Changes: receives database changes in real-time.

Channels#

A Channel is the basic building block of Realtime. You can think of a Channel as a chatroom, similar to a Discord or Slack channel, where participants are able to see who's online and send and receive messages.

When you initialize your Supabase Realtime client, you define a topic that uniquely references a channel. Clients can bi-directionally send and receive messages over a Channel.

1
2
3
4
5
import { createClient } from '@supabase/supabase-js'const supabase = createClient('https://<project>.supabase.co', '<your-anon-key>')const roomOne = supabase.channel('room-one') // set your topic here

Authorization#

Authorization is done via RLS policies against the table realtime.messages which will determine if a user can connect to a Channel and if they are allowed to send messages to a Channel.

By default, channels are public and you need to set that you want to use a private channel.

1
2
3
import { createClient } from '@supabase/supabase-js'const supabase = createClient('https://<project>.supabase.co', '<your-anon-key>')const roomOne = supabase.channel('private-room-one', { config: { private: true } })

Broadcast#

Realtime Broadcast follows the publish-subscribe pattern where a client publishes messages to a channel based on a unique topic. For example, a user could send a message to a channel with topic room-one.

1
2
3
4
5
roomOne.send({  type: 'broadcast',  event: 'test',  payload: { message: 'hello, world' },})

Other clients can receive the message in real-time by subscribing to the Channel with topic room-one. These clients continue to receive messages as long as they are subscribed and connected to the same Channel topic.

You can also use [Broadcast using the REST API](/docs/guides/realtime/broad cast#broadcast-using-the-rest-api) and Broadcast using the Database to send messages to a Channel which allows you to do more advanced use-cases.

An example use-case is sharing a user's cursor position with other clients in an online game.

Presence#

Presence can be used to share an individual's state with others within a Channel.

1
2
3
4
const presenceTrackStatus = await roomOne.track({  user: 'user-1',  online_at: new Date().toISOString(),})

Each client maintains their own state, and this is then combined into a "shared state" for that Channel topic. It's commonly used for sharing statuses (e.g. "online" or "inactive"). The neat thing about Presence is that if a client is suddenly disconnected (for example, they go offline), their state is automatically removed from the shared state. If you've ever tried to build an “I'm online” feature which handles unexpected disconnects, you'll appreciate how useful this is. When a new client subscribes to a channel, it will immediately receive the channel's latest state in a single message because the state is held by the Realtime server.

Postgres Changes#

The Postgres Changes extension listens for database changes and sends them to clients. Clients are required to subscribe with a JWT dictating which changes they are allowed to receive based on the database's Row Level Security.

1
2
3
4
5
6
7
8
9
10
11
const allChanges = supabase  .channel('schema-db-changes')  .on(    'postgres_changes',    {      event: '*',      schema: 'public',    },    (payload) => console.log(payload)  )  .subscribe()

Anyone with access to a valid JWT signed with the project's JWT secret is able to listen to your database's changes, unless tables have Row Level Security enabled and policies in place.

Clients can choose to receive INSERT, UPDATE, DELETE, or * (all) changes for all changes in a schema, a table in a schema, or a column's value in a table. Your clients should only listen to tables in the public schema and you must first enable the tables you want your clients to listen to.

Settings#

You can set the following settings using the Realtime Settings screen in your Dashboard:

• Channel Restrictions: You can toggle this settings to set Realtime to allow public channels or set it to use only private channels with Realtime Authorization.
• Database connection pool size: Determines the number of connections used for Realtime Authorization RLS checking
• Max concurrent clients: Determines the maximum number of clients that can be connected

All changes made in this screen will disconnect all your connected clients to ensure Realtime starts with the appropriate settings and all changes are stored in Supabase middleware.

Choosing between Broadcast and Postgres Changes for database changes#

We recommend using Broadcast by default and using Broadcast from Database specifically as it will allow you to scale your application compared to Postgres Changes.

Choosing between Broadcast and Presence#

We recommend using Broadcast by default, and then Presence when required. Presence utilizes an in-memory conflict-free replicated data type (CRDT) to track and synchronize shared state in an eventually consistent manner. It computes the difference between existing state and new state changes and sends the necessary updates to clients via Broadcast. This is computationally heavy, so you should use it sparingly. If you use Presence, it's best to throttle your changes so that you are sending updates less frequently.