Bring Your Own Database

Realtime Database Changes works with any Postgres database that has logical replication enabled and the wal2json extension installed.


After setting up your database for Realtime, submit a support ticket if you want to use your database with hosted Supabase Realtime.

The following steps will make sure that your database is properly set up to work with Realtime.

wal2json Extension#

Realtime relies on the wal2json Postgres extension to format database changes to JSON which are then sent to Realtime subscribers.

Postgres databases managed by AWS RDS and Google Cloud SQL should already have wal2json installed. Please check to make sure this is indeed the case with your Postgres database.

Logical Replication Configuration#

Realtime relies on Postgres' logical replication functionality to get database changes. Please enable logical replication on your database and configure the following settings:

  • max_replication_slots: we recommend 10 because Realtime requires a few slots plus the slots you'll need for your non-Realtime logical replication needs.
  • max_slot_wal_keep_size: we recommend 1024 (MB) so Realtime can attempt to deliver more database changes stored in Postgres.

Realtime Database Setup#

supabase_realtime Publication#

Create supabase_realtime publication and add tables you want Realtime to listen to:

create publication supabase_realtime with (publish = 'insert, update, delete');

alter publication supabase_realtime add table messages, users;


If the payload contains a 401 Unauthorized then you will need to grant select privileges to the table for the database role you want to authorize to receive database changes:

grant select on table messages to anon;

realtime Schema#

Create a realtime schema:

create schema realtime;

supabase_realtime_admin Role#

Create a supabase_realtime_admin database role and grant it replication permissions:

create role supabase_realtime_admin with noinherit login password 'secure-password';

Make sure to grant supabase_realtime_admin role with replication permissions. This step will vary based on your database provider.

For example, if your database is managed by AWS RDS then you can run:

grant rds_replication to supabase_realtime_admin;

supabase_realtime_admin Privileges#

Grant supabase_realtime_admin privileges for realtime schema and all related Realtime objects:

grant all on schema realtime to supabase_realtime_admin;
grant all on all tables in schema realtime to supabase_realtime_admin;
grant all on all sequences in schema realtime to supabase_realtime_admin;
grant all on all routines in schema realtime to supabase_realtime_admin;

authenticated Role#

Create an authenticated role:

create role authenticated nologin noinherit;


This role is hardcoded into Realtime migrations so it's required for the time being.