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

Database connections

Realtime uses several database connections to perform various operations. You can configure some of these connections through Realtime Settings.

The connections include:

• Migrations: Two temporary connections to run database migrations when needed
• Authorization: Configurable connection pool to check authorization policies on join that are always started.
• Broadcast from database: One connection to receive data from replication slot used to broadcast the changes to the clients that is always started.
• Postgres Changes: Multiple connection pools required. These pools are only started if you use Postgres Changes.
  • 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 your compute add-on size and configuration. The following table shows the default connection pool sizes for different compute add-on variants:

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:

    create table realtime.messages (
    topic text not null, -- The topic of the message
    extension text not null, -- The extension of the message (presence, broadcast)
    payload jsonb null, -- The payload of the message
    event text null, -- The event of the message
    private boolean null default false, -- If the message is going to use a private channel
    updated_at timestamp without time zone not null default now(), -- The timestamp of the message
    inserted_at timestamp without time zone not null default now(), -- The timestamp of the message
    id uuid not null default gen_random_uuid (), -- The id of the message
    constraint messages_pkey primary key (id, inserted_at)) partition by RANGE (inserted_at);

Functions

Realtime creates some 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.send_binary - Similar to realtime.send but allows you to broadcast binaries.
• realtime.broadcast_changes - uses realtime.send to broadcast the changes with a format that is compatible with Postgres Changes