on().subscribe()

Listen to messages.

1supabase
2  .channel('*')
3  .on('postgres_changes', { event: '*', schema: '*' }, payload => {
4    console.log('Change received!', payload)
5  })
6  .subscribe()

Parameters#

  • typerequired
    object

    No description provided.

  • filterrequired
    object

    No description provided.

      Properties

    • eventrequired
      string

      No description provided.

  • callbackrequired
    object

    No description provided.

Notes#

  • Realtime is disabled by default for new Projects for better database performance and security. You can turn it on by managing replication.
  • Row level security is not applied to delete statements.
  • If you want to receive the "previous" data for updates and deletes, you will need to set REPLICA IDENTITY to FULL, like this: ALTER TABLE your_table REPLICA IDENTITY FULL;
  • When a delete occurs, the contents of old_record will be broadcast to all subscribers to that table so ensure that each table's replica identity only contains information that is safe to expose publicly.
  • The channel name must exactly match the schema/table/filter you want to listen to separated by colons. See below examples for additional context.

Examples#

Listen to all database changes#

1supabase
2  .channel('*')
3  .on('postgres_changes', { event: '*', schema: '*' }, payload => {
4    console.log('Change received!', payload)
5  })
6  .subscribe()

Listening to a specific table#

1supabase
2  .channel('public:countries')
3  .on('postgres_changes', { event: '*', schema: 'public', table: 'countries' }, payload => {
4    console.log('Change received!', payload)
5  })
6  .subscribe()

Listening to inserts#

1supabase
2  .channel('public:countries')
3  .on('postgres_changes', { event: 'INSERT', schema: 'public', table: 'countries' }, payload => {
4    console.log('Change received!', payload)
5  })
6  .subscribe()

Listening to updates#

By default, Supabase will send only the updated record. If you want to receive the previous values as well you can enable full replication for the table you are listening to:

1alter table "your_table" replica identity full;
1supabase
2  .channel('public:countries')
3  .on('postgres_changes', { event: 'UPDATE', schema: 'public', table: 'countries' }, payload => {
4    console.log('Change received!', payload)
5  })
6  .subscribe()

Listening to deletes#

By default, Supabase does not send deleted records. If you want to receive the deleted record you can enable full replication for the table you are listening too:

1alter table "your_table" replica identity full;
1supabase
2  .channel('public:countries')
3  .on('postgres_changes', { event: 'DELETE', schema: 'public', table: 'countries' }, payload => {
4    console.log('Change received!', payload)
5  })
6  .subscribe()

Listening to multiple events#

You can chain listeners if you want to listen to multiple events for each table.

1supabase
2  .channel('public:countries')
3  .on('postgres_changes', { event: 'INSERT', schema: 'public', table: 'countries' }, handleRecordInserted)
4  .on('postgres_changes', { event: 'DELETE', schema: 'public', table: 'countries' }, handleRecordDeleted)
5  .subscribe()

Listening to row level changes#

You can listen to individual rows using the format {table}:{col}=eq.{val} - where {col} is the column name, and {val} is the value which you want to match.

1supabase
2  .channel('public:countries:id=eq.200')
3  .on('postgres_changes', { event: 'UPDATE', schema: 'public', table: 'countries', filter: 'id=eq.200' }, handleRecordUpdated)
4  .subscribe()