Realtime Concepts

Concepts#

There are several concepts and terminology that is useful to understand how Realtime works.

• Channels: the foundation of Realtime. Think of them as rooms where clients can communicate and listen to events. Channels are identified by a topic name and if they are public or private.
• Topics: the name of the channel. They are used to identify the channel and are a string used to identify the channel.
• Events: the type of messages that can be sent and received.
• Payload: the actual data that is sent and received and that the user will act upon.
• Concurrent Connections: number of total channels subscribed for all clients.

Channels#

Channels are the foundation of Realtime. Think of them as rooms where clients can communicate and listen to events. Channels are identified by a topic name and if they are public or private.

For private channels, you need to use Realtime Authorization to control access to the channel and if they are able to send messages. For public channels, any user can subscribe to the channel, send and receive messages.

You can set your project to use only private channels or both private and public channels in the Realtime Settings.

Database resources#

Realtime uses several database connections to perform several operations. As a user, you are able to tune some of them using Realtime Settings.

Database connections#

Realtime uses several database connections to do several operations. Some of them, as a user, you are able to tune them.

The connections are:

• Migrations: Two temporary connections to run database migrations when needed
• Authorization: Configurable connection pool to check authorization policies on join
• Postgres Changes: 3 connection pools required
  • Subscription management: To manage the subscribers to Postgres Changes
  • Subscription cleanup: To cleanup the subscribers to Postgres Changes
  • WAL pull: To pull the changes from the database

The number of connections varies based on the instance size and your configuration in Realtime Settings.

Replication slots#

Realtime also uses, at maximum, 2 replication slots.

• Broadcast from database: To broadcast the changes from the database to the clients
• Postgres Changes: To listen to changes from the database

Schema and tables#

The realtime schema creates the following tables:

• schema_migrations - To track the migrations that have been run on the database from Realtime
• subscription - Track the subscribers to Postgres Changes
• messages - Partitioned table per day that's used for Authorization and Broadcast from database
  • Authorization: To check the authorization policies on join by checking if a given user can read and write to this table
  • Broadcast from database: Replication slot tracks a publication to this table to broadcast the changes to the connected clients.
  • The schema from the table is the following:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    create table realtime.messages (topic text not null, -- The topic of the messageextension text not null, -- The extension of the message (presence, broadcast)payload jsonb null, -- The payload of the messageevent text null, -- The event of the messageprivate boolean null default false, -- If the message is going to use a private channelupdated_at timestamp without time zone not null default now(), -- The timestamp of the messageinserted_at timestamp without time zone not null default now(), -- The timestamp of the messageid uuid not null default gen_random_uuid (), -- The id of the messageconstraint messages_pkey primary key (id, inserted_at)) partition by RANGE (inserted_at);

Functions#

Realtime creates two functions on your database:

• realtime.send - Inserts an entry into realtime.messages table that will trigger the replication slot to broadcast the changes to the clients. It also captures errors to prevent the trigger from breaking.
• realtime.broadcast_changes - uses realtime.send to broadcast the changes with a format that is compatible with Postgres Changes