Skip to content

The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

chore: update pg changes documentation (#47593)

Filipe Cabaço0a9a0eec92ba
diff --git a/apps/docs/components/RealtimeLimitsEstimator/RealtimeLimitsEstimator.constants.ts b/apps/docs/components/RealtimeLimitsEstimator/RealtimeLimitsEstimator.constants.ts
index abf52483ef9..3b6cabbc1b9 100644
--- a/apps/docs/components/RealtimeLimitsEstimator/RealtimeLimitsEstimator.constants.ts
+++ b/apps/docs/components/RealtimeLimitsEstimator/RealtimeLimitsEstimator.constants.ts
@@ -14,7 +14,7 @@ export const COMPUTE_LABELS: Record<string, string> = Object.fromEntries(
)
// Input-parameter columns (only shown in the full/raw table).
-export const THROUGHPUT_PARAM_HEADINGS = ['Filters', 'RLS', 'Connected clients'] as const
+export const THROUGHPUT_PARAM_HEADINGS = ['RLS', 'Connected clients'] as const
// Result columns (shown in both the current-selection table and the raw table).
export const THROUGHPUT_METRIC_HEADINGS = [
diff --git a/apps/docs/components/RealtimeLimitsEstimator/RealtimeLimitsEstimator.tsx b/apps/docs/components/RealtimeLimitsEstimator/RealtimeLimitsEstimator.tsx
index de5402b9d3b..7f13c8bb837 100644
--- a/apps/docs/components/RealtimeLimitsEstimator/RealtimeLimitsEstimator.tsx
+++ b/apps/docs/components/RealtimeLimitsEstimator/RealtimeLimitsEstimator.tsx
@@ -22,49 +22,37 @@ import {
} from './RealtimeLimitsEstimator.constants'
export default function RealtimeLimitsEstimater({}) {
- const findTableValue = ({ computeAddOn, filters, rls, concurrency }) => {
+ const findTableValue = ({ computeAddOn, rls, concurrency }) => {
return throughputTable.find(
- (l) =>
- l.computeAddOn === computeAddOn &&
- l.filters === filters &&
- l.rls === rls &&
- l.concurrency === concurrency
+ (l) => l.computeAddOn === computeAddOn && l.rls === rls && l.concurrency === concurrency
)
}
const [computeAddOn, setComputeAddOn] = useState('micro')
- const [filters, setFilters] = useState(false)
const [rls, setRLS] = useState(false)
const [concurrency, setConcurrency] = useState(500)
- const [limits, setLimits] = useState(findTableValue({ computeAddOn, filters, rls, concurrency }))
+ const [limits, setLimits] = useState(findTableValue({ computeAddOn, rls, concurrency }))
const [expandPreview, setExpandPreview] = useState(false)
const handleComputeAddOnSelection = (val) => {
setComputeAddOn(val)
setConcurrency(500)
- setLimits(findTableValue({ computeAddOn: val, filters, rls, concurrency: 500 }))
- }
-
- const handleFiltersSelection = (value) => {
- const val = value.toLowerCase() === 'true'
- setFilters(val)
- setConcurrency(500)
- setLimits(findTableValue({ computeAddOn, filters: val, rls, concurrency: 500 }))
+ setLimits(findTableValue({ computeAddOn: val, rls, concurrency: 500 }))
}
const handleRLSSelection = (value) => {
const val = value.toLowerCase() === 'true'
setRLS(val)
setConcurrency(500)
- setLimits(findTableValue({ computeAddOn, filters, rls: val, concurrency: 500 }))
+ setLimits(findTableValue({ computeAddOn, rls: val, concurrency: 500 }))
}
const handleConcurrencySelection = (value) => {
const val = parseInt(value)
setConcurrency(val)
- setLimits(findTableValue({ computeAddOn, filters, rls, concurrency: val }))
+ setLimits(findTableValue({ computeAddOn, rls, concurrency: val }))
}
return (
@@ -86,18 +74,6 @@ export default function RealtimeLimitsEstimater({}) {
</SelectContent>
</Select>
</div>
- <div>
- <Label htmlFor="filters">Filters:</Label>
- <Select onValueChange={handleFiltersSelection} value={filters.toString()} disabled>
- <SelectTrigger id="filters">
- <SelectValue className="font-mono" />
- </SelectTrigger>
- <SelectContent>
- <SelectItem value="false">No</SelectItem>
- <SelectItem value="true">Yes</SelectItem>
- </SelectContent>
- </Select>
- </div>
<div>
<Label htmlFor="rls">RLS:</Label>
<Select onValueChange={handleRLSSelection} value={rls.toString()}>
@@ -118,9 +94,7 @@ export default function RealtimeLimitsEstimater({}) {
</SelectTrigger>
<SelectContent>
{throughputTable
- .filter(
- (l) => l.computeAddOn === computeAddOn && l.filters === filters && l.rls === rls
- )
+ .filter((l) => l.computeAddOn === computeAddOn && l.rls === rls)
.map((l) => (
<SelectItem key={l.concurrency} value={l.concurrency.toString()}>
{Intl.NumberFormat().format(l.concurrency)}
@@ -200,7 +174,6 @@ export default function RealtimeLimitsEstimater({}) {
.filter((l) => l.computeAddOn === computeAddOn)
.map((l) => (
<tr>
- <td className="border px-4 py-2">{l.filters ? '✅' : '🚫'}</td>
<td className="border px-4 py-2">{l.rls ? '✅' : '🚫'}</td>
<td className="border px-4 py-2">
{Intl.NumberFormat().format(l.concurrency)}
diff --git a/apps/docs/content/guides/realtime/postgres-changes.mdx b/apps/docs/content/guides/realtime/postgres-changes.mdx
index fc5673ed61b..d2ee8773622 100644
--- a/apps/docs/content/guides/realtime/postgres-changes.mdx
+++ b/apps/docs/content/guides/realtime/postgres-changes.mdx
@@ -320,7 +320,768 @@ changes = supabase.channel('schema-db-changes').on_postgres_changes(
The channel name can be any string except 'realtime'.
-### Listening to `INSERT` events
+### Listening to specific events
+
+Use the `event` parameter to listen only to a specific database event. `event` can be `INSERT`, `UPDATE`, `DELETE`, or `*` to listen to all changes.
+
+<Tabs
+ scrollable
+ size="small"
+ type="underlined"
+ defaultActiveId="js"
+ queryGroup="language"
+>
+<TabPanel id="js" label="JavaScript">
+
+<Tabs
+ scrollable
+ size="small"
+ type="underlined"
+ defaultActiveId="insert"
+ queryGroup="pg-changes-event"
+>
+<TabPanel id="insert" label="Insert">
+
+```js
+const changes = supabase
+ .channel('schema-db-changes')
+ .on(
+ 'postgres_changes',
+ {
+ event: 'INSERT',
+ schema: 'public',
+ },
+ (payload) => console.log(payload)
+ )
+ .subscribe()
+```
+
+</TabPanel>
+<TabPanel id="update" label="Update">
+
+```js
+const changes = supabase
+ .channel('schema-db-changes')
+ .on(
+ 'postgres_changes',
+ {
+ event: 'UPDATE',
+ schema: 'public',
+ },
+ (payload) => console.log(payload)
+ )
+ .subscribe()
+```
+
+</TabPanel>
+<TabPanel id="delete" label="Delete">
+
+```js
+const changes = supabase
+ .channel('schema-db-changes')
+ .on(
+ 'postgres_changes',
+ {
+ event: 'DELETE',
+ schema: 'public',
+ },
+ (payload) => console.log(payload)
+ )
+ .subscribe()
+```
+
+</TabPanel>
+<TabPanel id="all" label="All events">
+
+```js
+const changes = supabase
+ .channel('schema-db-changes')
+ .on(
+ 'postgres_changes',
+ {
+ event: '*',
+ schema: 'public',
+ },
+ (payload) => console.log(payload)
+ )
+ .subscribe()
+```
+
+</TabPanel>
+</Tabs>
+
+</TabPanel>
+<$Show if="sdk:dart">
+<TabPanel id="dart" label="Dart">
+
+<Tabs
+ scrollable
+ size="small"
+ type="underlined"
+ defaultActiveId="insert"
+ queryGroup="pg-changes-event"
+>
+<TabPanel id="insert" label="Insert">
+
+```dart
+supabase
+ .channel('schema-db-changes')
+ .onPostgresChanges(
+ event: PostgresChangeEvent.insert,
+ schema: 'public',
+ callback: (payload) => print(payload))
+ .subscribe();
+```
+
+</TabPanel>
+<TabPanel id="update" label="Update">
+
+```dart
+supabase
+ .channel('schema-db-changes')
+ .onPostgresChanges(
+ event: PostgresChangeEvent.update,
+ schema: 'public',
+ callback: (payload) => print(payload))
+ .subscribe();
+```
+
+</TabPanel>
+<TabPanel id="delete" label="Delete">
+
+```dart
+supabase
+ .channel('schema-db-changes')
+ .onPostgresChanges(
+ event: PostgresChangeEvent.delete,
+ schema: 'public',
+ callback: (payload) => print(payload))
+ .subscribe();
+```
+
+</TabPanel>
+<TabPanel id="all" label="All events">
+
+```dart
+supabase
+ .channel('schema-db-changes')
+ .onPostgresChanges(
+ event: PostgresChangeEvent.all,
+ schema: 'public',
+ callback: (payload) => print(payload))
+ .subscribe();
+```
+
+</TabPanel>
+</Tabs>
+
+</TabPanel>
+</$Show>
+<$Show if="sdk:swift">
+<TabPanel id="swift" label="Swift">
+
+Pass the action type to select the event.
+
+<Tabs
+ scrollable
+ size="small"
+ type="underlined"
+ defaultActiveId="insert"
+ queryGroup="pg-changes-event"
+>
+<TabPanel id="insert" label="Insert">
+
+```swift
+let myChannel = await supabase.channel("schema-db-changes")
+
+let changes = await myChannel.postgresChange(InsertAction.self, schema: "public")
+
+await myChannel.subscribe()
+
+for await change in changes {
+ print(change.record)
+}
+```
+
+</TabPanel>
+<TabPanel id="update" label="Update">
+
+```swift
+let myChannel = await supabase.channel("schema-db-changes")
+
+let changes = await myChannel.postgresChange(UpdateAction.self, schema: "public")
+
+await myChannel.subscribe()
+
+for await change in changes {
+ print(change.record)
+}
+```
+
+</TabPanel>
+<TabPanel id="delete" label="Delete">
+
+```swift
+let myChannel = await supabase.channel("schema-db-changes")
+
+let changes = await myChannel.postgresChange(DeleteAction.self, schema: "public")
+
+await myChannel.subscribe()
+
+for await change in changes {
+ print(change.oldRecord)
+}
+```
+
+</TabPanel>
+<TabPanel id="all" label="All events">
+
+```swift
+let myChannel = await supabase.channel("schema-db-changes")
+
+let changes = await myChannel.postgresChange(AnyAction.self, schema: "public")
+
+await myChannel.subscribe()
+
+for await change in changes {
+ switch change {
+ case .insert(let action): print(action.record)
+ case .update(let action): print(action.record)
+ case .delete(let action): print(action.oldRecord)
+ case .select(let action): print(action.record)
+ }
+}
+```
+
+</TabPanel>
+</Tabs>
+
+</TabPanel>
+</$Show>
+<$Show if="sdk:kotlin">
+<TabPanel id="kotlin" label="Kotlin">
+
+Pass the action type to select the event.
+
+<Tabs
+ scrollable
+ size="small"
+ type="underlined"
+ defaultActiveId="insert"
+ queryGroup="pg-changes-event"
+>
+<TabPanel id="insert" label="Insert">
+
+```kotlin
+val myChannel = supabase.channel("db-changes")
+
+val changes = myChannel.postgresChangeFlow<PostgresAction.Insert>(schema = "public")
+
+changes
+ .onEach {
+ println(it.record)
+ }
+ .launchIn(yourCoroutineScope)
+
+myChannel.subscribe()
+```
+
+</TabPanel>
+<TabPanel id="update" label="Update">
+
+```kotlin
+val myChannel = supabase.channel("db-changes")
+
+val changes = myChannel.postgresChangeFlow<PostgresAction.Update>(schema = "public")
+
+changes
+ .onEach {
+ println(it.record)
+ }
+ .launchIn(yourCoroutineScope)
+
+myChannel.subscribe()
+```
+
+</TabPanel>
+<TabPanel id="delete" label="Delete">
+
+```kotlin
+val myChannel = supabase.channel("db-changes")
+
+val changes = myChannel.postgresChangeFlow<PostgresAction.Delete>(schema = "public")
+
+changes
+ .onEach {
+ println(it.oldRecord)
+ }
+ .launchIn(yourCoroutineScope)
+
+myChannel.subscribe()
+```
+
+</TabPanel>
+<TabPanel id="all" label="All events">
+
+```kotlin
+val myChannel = supabase.channel("db-changes")
+
+val changes = myChannel.postgresChangeFlow<PostgresAction>(schema = "public")
+
+changes
+ .onEach {
+ when (it) { //You can also check for <is PostgresAction.Insert>, etc.. manually
+ is HasRecord -> println(it.record)
+ is HasOldRecord -> println(it.oldRecord)
+ else -> println(it)
+ }
+ }
+ .launchIn(yourCoroutineScope)
+
+myChannel.subscribe()
+```
+
+</TabPanel>
+</Tabs>
+
+</TabPanel>
+</$Show>
+<$Show if="sdk:python">
+<TabPanel id="python" label="Python">
+
+<Tabs
+ scrollable
+ size="small"
+ type="underlined"
+ defaultActiveId="insert"
+ queryGroup="pg-changes-event"
+>
+<TabPanel id="insert" label="Insert">
+
+```python
+changes = supabase.channel('schema-db-changes').on_postgres_changes(
+ "INSERT",
+ schema="public",
+ callback=lambda payload: print(payload)
+)
+.subscribe()
+```
+
+</TabPanel>
+<TabPanel id="update" label="Update">
+
+```python
+changes = supabase.channel('schema-db-changes').on_postgres_changes(
+ "UPDATE",
+ schema="public",
+ callback=lambda payload: print(payload)
+)
+.subscribe()
+```
+
+</TabPanel>
+<TabPanel id="delete" label="Delete">
+
+```python
+changes = supabase.channel('schema-db-changes').on_postgres_changes(
+ "DELETE",
+ schema="public",
+ callback=lambda payload: print(payload)
+)
+.subscribe()
+```
+
+</TabPanel>
+<TabPanel id="all" label="All events">
+
+```python
+changes = supabase.channel('schema-db-changes').on_postgres_changes(
+ "*",
+ schema="public",
+ callback=lambda payload: print(payload)
+)
+.subscribe()
+```
+
+</TabPanel>
+</Tabs>
+
+</TabPanel>
+</$Show>
+</Tabs>
+
+The channel name can be any string except 'realtime'.
+
+### Listening to specific tables
+
+Subscribe to specific table events using the `table` parameter:
+
+<Tabs
+ scrollable
+ size="small"
+ type="underlined"
+ defaultActiveId="js"
+ queryGroup="language"
+>
+<TabPanel id="js" label="JavaScript">
+
+```js
+const changes = supabase
+ .channel('table-db-changes')
+ .on(
+ 'postgres_changes',
+ {
+ event: '*',
+ schema: 'public',
+ table: 'todos',
+ },
+ (payload) => console.log(payload)
+ )
+ .subscribe()
+```
+
+</TabPanel>
+<$Show if="sdk:dart">
+<TabPanel id="dart" label="Dart">
+
+```dart
+supabase
+ .channel('table-db-changes')
+ .onPostgresChanges(
+ event: PostgresChangeEvent.all,
+ schema: 'public',
+ table: 'todos',
+ callback: (payload) => print(payload))
+ .subscribe();
+```
+
+</TabPanel>
+</$Show>
+<$Show if="sdk:swfit">
+<TabPanel id="swift" label="Swift">
+
+```swift
+let myChannel = await supabase.channel("db-changes")
+
+let changes = await myChannel.postgresChange(AnyAction.self, schema: "public", table: "todos")
+
+await myChannel.subscribe()
+
+for await change in changes {
+ switch change {
+ case .insert(let action): print(action)
+ case .update(let action): print(action)
+ case .delete(let action): print(action)
+ case .select(let action): print(action)
+ }
+}
+```
+
+</TabPanel>
+</$Show>
+<$Show if="sdk:kotlin">
+<TabPanel id="kotlin" label="Kotlin">
+
+```kotlin
+val myChannel = supabase.channel("db-changes")
+
+val changes = myChannel.postgresChangeFlow<PostgresAction>(schema = "public") {
+ table = "todos"
+}
+
+changes
+ .onEach {
+ println(it.record)
+ }
+ .launchIn(yourCoroutineScope)
+
+myChannel.subscribe()
+```
+
+</TabPanel>
+</$Show>
+<$Show if="sdk:python">
+<TabPanel id="python" label="Python">
+
+```python
+changes = supabase.channel('db-changes').on_postgres_changes(
+ "UPDATE",
+ schema="public",
+ table="todos",
+ callback=lambda payload: print(payload)
+)
+.subscribe()
+```
+
+</TabPanel>
+</$Show>
+</Tabs>
+
+The channel name can be any string except 'realtime'.
+
+### Listening to multiple changes
+
+To listen to different events and schema/tables/filters combinations with the same channel:
+
+<Tabs
+ scrollable
+ size="small"
+ type="underlined"
+ defaultActiveId="js"
+ queryGroup="language"
+>
+<TabPanel id="js" label="JavaScript">
+
+```js
+const channel = supabase
+ .channel('db-changes')
+ .on(
+ 'postgres_changes',
+ {
+ event: '*',
+ schema: 'public',
+ table: 'messages',
+ },
+ (payload) => console.log(payload)
+ )
+ .on(
+ 'postgres_changes',
+ {
+ event: 'INSERT',
+ schema: 'public',
+ table: 'users',
+ },
+ (payload) => console.log(payload)
+ )
+ .subscribe()
+```
+
+</TabPanel>
+<$Show if="sdk:dart">
+<TabPanel id="dart" label="Dart">
+
+```dart
+supabase
+ .channel('db-changes')
+ .onPostgresChanges(
+ event: PostgresChangeEvent.all,
+ schema: 'public',
+ table: 'messages',
+ callback: (payload) => print(payload))
+ .onPostgresChanges(
+ event: PostgresChangeEvent.insert,
+ schema: 'public',
+ table: 'users',
+ callback: (payload) => print(payload))
+ .subscribe();
+```
+
+</TabPanel>
+</$Show>
+<$Show if="sdk:swift">
+<TabPanel id="swift" label="Swift">
+
+```swift
+let myChannel = await supabase.channel("db-changes")
+
+let messageChanges = await myChannel.postgresChange(AnyAction.self, schema: "public", table: "messages")
+let userChanges = await myChannel.postgresChange(InsertAction.self, schema: "public", table: "users")
+
+await myChannel.subscribe()
+```
+
+</TabPanel>
+</$Show>
+<$Show if="sdk:kotlin">
+<TabPanel id="kotlin" label="Kotlin">
+
+```kotlin
+val myChannel = supabase.channel("db-changes")
+val messageChanges = myChannel.postgresChangeFlow<PostgresAction>(schema = "public") {
+ table = "messages"
+}
+val userChanges = myChannel.postgresChangeFlow<PostgresAction.Insert>(schema = "public") {
+ table = "users"
+}
+myChannel.subscribe()
+```
+
+</TabPanel>
+</$Show>
+<$Show if="sdk:python">
+<TabPanel id="python" label="Python">
+
+```python
+changes = supabase.channel('db-changes').on_postgres_changes(
+ "*",
+ schema="public",
+ table="messages"
+ callback=lambda payload: print(payload)
+).on_postgres_changes(
+ "INSERT",
+ schema="public",
+ table="users",
+ callback=lambda payload: print(payload)
+).subscribe()
+```
+
+</TabPanel>
+</$Show>
+</Tabs>
+
+### Filtering for specific changes
+
+Use the `filter` parameter for granular changes:
+
+<Tabs
+ scrollable
+ size="small"
+ type="underlined"
+ defaultActiveId="js"
+ queryGroup="language"
+>
+<TabPanel id="js" label="JavaScript">
+
+```js
+const changes = supabase
+ .channel('table-filter-changes')
+ .on(
+ 'postgres_changes',
+ {
+ event: 'INSERT',
+ schema: 'public',
+ table: 'todos',
+ filter: 'id=eq.1',
+ },
+ (payload) => console.log(payload)
+ )
+ .subscribe()
+```
+
+</TabPanel>
+<$Show if="sdk:dart">
+<TabPanel id="dart" label="Dart">
+
+```dart
+ supabase
+ .channel('table-filter-changes')
+ .onPostgresChanges(
+ event: PostgresChangeEvent.insert,
+ schema: 'public',
+ table: 'todos',
+ filter: PostgresChangeFilter(
+ type: PostgresChangeFilterType.eq,
+ column: 'id',
+ value: 1,
+ ),
+ callback: (payload) => print(payload))
+ .subscribe();
+```
+
+</TabPanel>
+</$Show>
+<$Show if="sdk:swift">
+<TabPanel id="swift" label="Swift">
+
+```swift
+let myChannel = await supabase.channel("db-changes")
+
+let changes = await myChannel.postgresChange(
+ InsertAction.self,
+ schema: "public",
+ table: "todos",
+ filter: .eq("id", value: 1)
+)
+
+await myChannel.subscribe()
+
+for await change in changes {
+ print(change.record)
+}
+```
+
+</TabPanel>
+</$Show>
+<$Show if="sdk:kotlin">
+<TabPanel id="kotlin" label="Kotlin">
+
+```kotlin
+val myChannel = supabase.channel("db-changes")
+
+val changes = myChannel.postgresChangeFlow<PostgresAction.Insert>(schema = "public") {
+ table = "todos"
+ filter = "id=eq.1"
+}
+
+changes
+ .onEach {
+ println(it.record)
+ }
+ .launchIn(yourCoroutineScope)
+
+myChannel.subscribe()
+```
+
+</TabPanel>
+</$Show>
+<$Show if="sdk:python">
+<TabPanel id="python" label="Python">
+
+```python
+changes = supabase.channel('db-changes').on_postgres_changes(
+ "INSERT",
+ schema="public",
+ table="todos",
+ filter="id=eq.1",
+ callback=lambda payload: print(payload)
+)
+.subscribe()
+```
+
+</TabPanel>
+</$Show>
+</Tabs>
+
+## Available filters
+
+Realtime offers filters so you can specify the data your client receives at a more granular level. A filter is a `column=operator.value` expression (for example `id=eq.1` or `title=like.%foo%`) that Realtime evaluates on the server, so filtered-out events never leave the database.
+
+The following operators are available:
+
+| Operator | Matches when the column… | Example |
+| ------------------ | ---------------------------------------------------- | ------------------------- |
+| `eq` | equals the value | `id=eq.1` |
+| `neq` | does not equal the value | `status=neq.done` |
+| `lt` / `lte` | is less than / less than or equal to | `age=lt.65` |
+| `gt` / `gte` | is greater than / greater than or equal to | `quantity=gte.10` |
+| `in` | is one of a list (max 100 values) | `name=in.(red,blue)` |
+| `like` / `ilike` | matches a pattern (case-sensitive / insensitive) | `title=like.%foo%` |
+| `match` / `imatch` | matches a POSIX regex (case-sensitive / insensitive) | `slug=match.^post-` |
+| `is` | `IS null` / `true` / `false` / `unknown` | `deleted_at=is.null` |
+| `isdistinct` | is distinct from the value (NULL-safe `!=`) | `state=isdistinct.active` |
+
+You can also [negate any operator](#negating-a-filter-not) with `not.` and [combine multiple conditions](#combining-filters-with-and) with commas (applied as an `AND`).
+
+<$Show if="sdk:js">
+
+<Admonition type="tip">
+
+In JavaScript you can pass a raw filter string, or build one with the type-safe `postgresChangesFilter()` helper, which handles operator names, negation, `AND` composition, and escaping for you:
+
+```js
+import { postgresChangesFilter } from '@supabase/supabase-js'
+
+// → 'quantity=gte.10,status=eq.open'
+const filter = postgresChangesFilter().gte('quantity', 10).eq('status', 'open')
+```
+
+</Admonition>
+
+</$Show>
+
+### Equal to (`eq`)
+
+To listen to changes when a column's value in a table equals a client-specified value:
<Tabs
scrollable
@@ -331,32 +1092,69 @@ The channel name can be any string except 'realtime'.
>
<TabPanel id="js" label="JavaScript">
-Use the `event` parameter to listen only to database `INSERT`s:
+<Tabs
+ scrollable
+ size="small"
+ type="underlined"
+ defaultActiveId="builder"
+ queryGroup="realtime-js-filter"
+>
+<TabPanel id="builder" label="Builder">
```js
-const changes = supabase
- .channel('schema-db-changes')
+const channel = supabase
+ .channel('changes')
+ .on(
+ 'postgres_changes',
+ {
+ event: 'UPDATE',
+ schema: 'public',
+ table: 'messages',
+ filter: postgresChangesFilter().eq('body', 'hey'),
+ },
+ (payload) => console.log(payload)
+ )
+ .subscribe()
+```
+
+</TabPanel>
+<TabPanel id="string" label="Filter string">
+
+```js
+const channel = supabase
+ .channel('changes')
.on(
'postgres_changes',
{
- event: 'INSERT', // Listen only to INSERTs
+ event: 'UPDATE',
schema: 'public',
+ table: 'messages',
+ filter: 'body=eq.hey',
},
(payload) => console.log(payload)
)
.subscribe()
```
+</TabPanel>
+</Tabs>
+
</TabPanel>
<$Show if="sdk:dart">
<TabPanel id="dart" label="Dart">
```dart
-final changes = supabase
- .channel('schema-db-changes')
+supabase
+ .channel('changes')
.onPostgresChanges(
- event: PostgresChangeEvent.insert,
+ event: PostgresChangeEvent.update,
schema: 'public',
+ table: 'messages',
+ filter: PostgresChangeFilter(
+ type: PostgresChangeFilterType.eq,
+ column: 'body',
+ value: 'hey',
+ ),
callback: (payload) => print(payload))
.subscribe();
```
@@ -366,12 +1164,15 @@ final changes = supabase
<$Show if="sdk:swift">
<TabPanel id="swift" label="Swift">
-Use `InsertAction.self` as type to listen only to database `INSERT`s:
-
```swift
-let myChannel = await supabase.channel("schema-db-changes")
+let myChannel = await supabase.channel("db-changes")
-let changes = await myChannel.postgresChange(InsertAction.self, schema: "public")
+let changes = await myChannel.postgresChange(
+ UpdateAction.self,
+ schema: "public",
+ table: "messages",
+ filter: .eq("body", value: "hey")
+)
await myChannel.subscribe()
@@ -385,12 +1186,13 @@ for await change in changes {
<$Show if="sdk:kotlin">
<TabPanel id="kotlin" label="Kotlin">
-Use `PostgresAction.Insert` as type to listen only to database `INSERT`s:
-
```kotlin
val myChannel = supabase.channel("db-changes")
-val changes = myChannel.postgresChangeFlow<PostgresAction.Insert>(schema = "public")
+val changes = myChannel.postgresChangeFlow<PostgresAction.Update>(schema = "public") {
+ table = "messages"
+ filter = "body=eq.hey"
+}
changes
.onEach {
@@ -407,9 +1209,11 @@ myChannel.subscribe()
<TabPanel id="python" label="Python">
```python
-changes = supabase.channel('schema-db-changes').on_postgres_changes(
- "INSERT", # Listen only to INSERTs
+changes = supabase.channel('db-changes').on_postgres_changes(
+ "UPDATE",
schema="public",
+ table="messages",
+ filter="body=eq.hey",
callback=lambda payload: print(payload)
)
.subscribe()
@@ -419,9 +1223,11 @@ changes = supabase.channel('schema-db-changes').on_postgres_changes(
</$Show>
</Tabs>
-The channel name can be any string except 'realtime'.
+This filter uses Postgres's `=` filter.
-### Listening to `UPDATE` events
+### Not equal to (`neq`)
+
+To listen to changes when a column's value in a table does not equal a client-specified value:
<Tabs
scrollable
@@ -432,32 +1238,69 @@ The channel name can be any string except 'realtime'.
>
<TabPanel id="js" label="JavaScript">
-Use the `event` parameter to listen only to database `UPDATE`s:
+<Tabs
+ scrollable
+ size="small"
+ type="underlined"
+ defaultActiveId="builder"
+ queryGroup="realtime-js-filter"
+>
+<TabPanel id="builder" label="Builder">
```js
-const changes = supabase
- .channel('schema-db-changes')
+const channel = supabase
+ .channel('changes')
+ .on(
+ 'postgres_changes',
+ {
+ event: 'INSERT',
+ schema: 'public',
+ table: 'messages',
+ filter: postgresChangesFilter().neq('body', 'bye'),
+ },
+ (payload) => console.log(payload)
+ )
+ .subscribe()
+```
+
+</TabPanel>
+<TabPanel id="string" label="Filter string">
+
+```js
+const channel = supabase
+ .channel('changes')
.on(
'postgres_changes',
{
- event: 'UPDATE', // Listen only to UPDATEs
+ event: 'INSERT',
schema: 'public',
+ table: 'messages',
+ filter: 'body=neq.bye',
},
(payload) => console.log(payload)
)
.subscribe()
```
+</TabPanel>
+</Tabs>
+
</TabPanel>
<$Show if="sdk:dart">
<TabPanel id="dart" label="Dart">
```dart
supabase
- .channel('schema-db-changes')
+ .channel('changes')
.onPostgresChanges(
- event: PostgresChangeEvent.update, // Listen only to UPDATEs
+ event: PostgresChangeEvent.insert,
schema: 'public',
+ table: 'messages',
+ filter: PostgresChangeFilter(
+ type: PostgresChangeFilterType.neq,
+ column: 'body',
+ value: 'bye',
+ ),
callback: (payload) => print(payload))
.subscribe();
```
@@ -467,17 +1310,167 @@ supabase
<$Show if="sdk:swift">
<TabPanel id="swift" label="Swift">
-Use `UpdateAction.self` as type to listen only to database `UPDATE`s:
+```swift
+let myChannel = await supabase.channel("db-changes")
+
+let changes = await myChannel.postgresChange(
+ UpdateAction.self,
+ schema: "public",
+ table: "messages",
+ filter: .neq("body", value: "hey")
+)
+
+await myChannel.subscribe()
+
+for await change in changes {
+ print(change.record)
+}
+```
+
+</TabPanel>
+</$Show>
+<$Show if="sdk:kotlin">
+<TabPanel id="kotlin" label="Kotlin">
+
+```kotlin
+val myChannel = supabase.realtime.createChannel("db-changes")
+
+val changes = myChannel.postgresChangeFlow<PostgresAction.Update>(schema = "public") {
+ table = "messages"
+ filter = "body=neq.bye"
+}
+
+changes
+ .onEach {
+ println(it.record)
+ }
+ .launchIn(yourCoroutineScope)
+
+supabase.realtime.connect()
+myChannel.join()
+```
+
+</TabPanel>
+</$Show>
+<$Show if="sdk:python">
+<TabPanel id="python" label="Python">
+
+```python
+changes = supabase.channel('db-changes').on_postgres_changes(
+ "INSERT",
+ schema="public",
+ table="messages",
+ filter="body=neq.bye",
+ callback=lambda payload: print(payload)
+)
+.subscribe()
+```
+
+</TabPanel>
+</$Show>
+</Tabs>
+
+This filter uses Postgres's `!=` filter.
+
+### Less than (`lt`)
+
+To listen to changes when a column's value in a table is less than a client-specified value:
+
+<Tabs
+ scrollable
+ size="small"
+ type="underlined"
+ defaultActiveId="js"
+ queryGroup="language"
+>
+<TabPanel id="js" label="JavaScript">
+
+<Tabs
+ scrollable
+ size="small"
+ type="underlined"
+ defaultActiveId="builder"
+ queryGroup="realtime-js-filter"
+>
+<TabPanel id="builder" label="Builder">
+
+```js
+const channel = supabase
+ .channel('changes')
+ .on(
+ 'postgres_changes',
+ {
+ event: 'INSERT',
+ schema: 'public',
+ table: 'profiles',
+ filter: postgresChangesFilter().lt('age', 65),
+ },
+ (payload) => console.log(payload)
+ )
+ .subscribe()
+```
+
+</TabPanel>
+<TabPanel id="string" label="Filter string">
+
+```js
+const channel = supabase
+ .channel('changes')
+ .on(
+ 'postgres_changes',
+ {
+ event: 'INSERT',
+ schema: 'public',
+ table: 'profiles',
+ filter: 'age=lt.65',
+ },
+ (payload) => console.log(payload)
+ )
+ .subscribe()
+```
+
+</TabPanel>
+</Tabs>
+
+</TabPanel>
+<$Show if="sdk:dart">
+<TabPanel id="dart" label="Dart">
+
+```dart
+supabase
+ .channel('changes')
+ .onPostgresChanges(
+ event: PostgresChangeEvent.insert,
+ schema: 'public',
+ table: 'profiles',
+ filter: PostgresChangeFilter(
+ type: PostgresChangeFilterType.lt,
+ column: 'age',
+ value: 65,
+ ),
+ callback: (payload) => print(payload))
+ .subscribe();
+```
+
+</TabPanel>
+</$Show>
+<$Show if="sdk:swift">
+<TabPanel id="swift" label="Swift">
```swift
-let myChannel = await supabase.channel("schema-db-changes")
+let myChannel = await supabase.channel("db-changes")
-let changes = await myChannel.postgresChange(UpdateAction.self, schema: "public")
+let changes = await myChannel.postgresChange(
+ InsertAction.self,
+ schema: "public",
+ table: "profiles",
+ filter: .lt("age", value: 65)
+)
await myChannel.subscribe()
for await change in changes {
- print(change.oldRecord, change.record)
+ print(change.record)
}
```
@@ -486,12 +1479,13 @@ for await change in changes {
<$Show if="sdk:kotlin">
<TabPanel id="kotlin" label="Kotlin">
-Use `PostgresAction.Update` as type to listen only to database `UPDATE`s:
-
```kotlin
val myChannel = supabase.channel("db-changes")
-val changes = myChannel.postgresChangeFlow<PostgresAction.Update>(schema = "public")
+val changes = myChannel.postgresChangeFlow<PostgresAction.Insert>(schema = "public") {
+ table = "profiles"
+ filter = "age=lt.65"
+}
changes
.onEach {
@@ -508,9 +1502,11 @@ myChannel.subscribe()
<TabPanel id="python" label="Python">
```python
-changes = supabase.channel('schema-db-changes').on_postgres_changes(
- "UPDATE", # Listen only to UPDATEs
+changes = supabase.channel('db-changes').on_postgres_changes(
+ "INSERT",
schema="public",
+ table="profiles",
+ filter="age=lt.65",
callback=lambda payload: print(payload)
)
.subscribe()
@@ -520,9 +1516,11 @@ changes = supabase.channel('schema-db-changes').on_postgres_changes(
</$Show>
</Tabs>
-The channel name can be any string except 'realtime'.
+This filter uses Postgres's `<` filter, so it works for non-numeric types. Make sure to check the expected behavior of the compared data's type.
-### Listening to `DELETE` events
+### Less than or equal to (`lte`)
+
+To listen to changes when a column's value in a table is less than or equal to a client-specified value:
<Tabs
scrollable
@@ -533,32 +1531,69 @@ The channel name can be any string except 'realtime'.
>
<TabPanel id="js" label="JavaScript">
-Use the `event` parameter to listen only to database `DELETE`s:
+<Tabs
+ scrollable
+ size="small"
+ type="underlined"
+ defaultActiveId="builder"
+ queryGroup="realtime-js-filter"
+>
+<TabPanel id="builder" label="Builder">
```js
-const changes = supabase
- .channel('schema-db-changes')
+const channel = supabase
+ .channel('changes')
.on(
'postgres_changes',
{
- event: 'DELETE', // Listen only to DELETEs
+ event: 'UPDATE',
+ schema: 'public',
+ table: 'profiles',
+ filter: postgresChangesFilter().lte('age', 65),
+ },
+ (payload) => console.log(payload)
+ )
+ .subscribe()
+```
+
+</TabPanel>
+<TabPanel id="string" label="Filter string">
+
+```js
+const channel = supabase
+ .channel('changes')
+ .on(
+ 'postgres_changes',
+ {
+ event: 'UPDATE',
schema: 'public',
+ table: 'profiles',
+ filter: 'age=lte.65',
},
(payload) => console.log(payload)
)
.subscribe()
```
+</TabPanel>
+</Tabs>
+
</TabPanel>
<$Show if="sdk:dart">
<TabPanel id="dart" label="Dart">
```dart
supabase
- .channel('schema-db-changes')
+ .channel('changes')
.onPostgresChanges(
- event: PostgresChangeEvent.delete, // Listen only to DELETEs
+ event: PostgresChangeEvent.insert,
schema: 'public',
+ table: 'profiles',
+ filter: PostgresChangeFilter(
+ type: PostgresChangeFilterType.lte,
+ column: 'age',
+ value: 65,
+ ),
callback: (payload) => print(payload))
.subscribe();
```
@@ -568,17 +1603,20 @@ supabase
<$Show if="sdk:swift">
<TabPanel id="swift" label="Swift">
-Use `DeleteAction.self` as type to listen only to database `DELETE`s:
-
```swift
-let myChannel = await supabase.channel("schema-db-changes")
+let myChannel = await supabase.channel("db-changes")
-let changes = await myChannel.postgresChange(DeleteAction.self, schema: "public")
+let changes = await myChannel.postgresChange(
+ InsertAction.self,
+ schema: "public",
+ table: "profiles",
+ filter: .lte("age", value: 65)
+)
await myChannel.subscribe()
for await change in changes {
- print(change.oldRecord)
+ print(change.record)
}
```
@@ -587,16 +1625,17 @@ for await change in changes {
<$Show if="sdk:kotlin">
<TabPanel id="kotlin" label="Kotlin">
-Use `PostgresAction.Delete` as type to listen only to database `DELETE`s:
-
```kotlin
val myChannel = supabase.channel("db-changes")
-val changes = myChannel.postgresChangeFlow<PostgresAction.Delete>(schema = "public")
+val changes = myChannel.postgresChangeFlow<PostgresAction.Update>(schema = "public") {
+ table = "profiles"
+ filter = "age=lte.65"
+}
changes
.onEach {
- println(it.oldRecord)
+ println(it.record)
}
.launchIn(yourCoroutineScope)
@@ -609,9 +1648,11 @@ myChannel.subscribe()
<TabPanel id="python" label="Python">
```python
-changes = supabase.channel('schema-db-changes').on_postgres_changes(
- "DELETE", # Listen only to DELETEs
+changes = supabase.channel('db-changes').on_postgres_changes(
+ "UPDATE",
schema="public",
+ table="profiles",
+ filter="age=lte.65",
callback=lambda payload: print(payload)
)
.subscribe()
@@ -621,11 +1662,11 @@ changes = supabase.channel('schema-db-changes').on_postgres_changes(
</$Show>
</Tabs>
-The channel name can be any string except 'realtime'.
+This filter uses Postgres' `<=` filter, so it works for non-numeric types. Make sure to check the expected behavior of the compared data's type.
-### Listening to specific tables
+### Greater than (`gt`)
-Subscribe to specific table events using the `table` parameter:
+To listen to changes when a column's value in a table is greater than a client-specified value:
<Tabs
scrollable
@@ -636,55 +1677,92 @@ Subscribe to specific table events using the `table` parameter:
>
<TabPanel id="js" label="JavaScript">
+<Tabs
+ scrollable
+ size="small"
+ type="underlined"
+ defaultActiveId="builder"
+ queryGroup="realtime-js-filter"
+>
+<TabPanel id="builder" label="Builder">
+
```js
-const changes = supabase
- .channel('table-db-changes')
+const channel = supabase
+ .channel('changes')
.on(
'postgres_changes',
{
- event: '*',
+ event: 'INSERT',
schema: 'public',
- table: 'todos',
+ table: 'products',
+ filter: postgresChangesFilter().gt('quantity', 10),
+ },
+ (payload) => console.log(payload)
+ )
+ .subscribe()
+```
+
+</TabPanel>
+<TabPanel id="string" label="Filter string">
+
+```js
+const channel = supabase
+ .channel('changes')
+ .on(
+ 'postgres_changes',
+ {
+ event: 'INSERT',
+ schema: 'public',
+ table: 'products',
+ filter: 'quantity=gt.10',
},
(payload) => console.log(payload)
)
.subscribe()
```
+</TabPanel>
+</Tabs>
+
</TabPanel>
<$Show if="sdk:dart">
<TabPanel id="dart" label="Dart">
```dart
supabase
- .channel('table-db-changes')
+ .channel('changes')
.onPostgresChanges(
- event: PostgresChangeEvent.all,
+ event: PostgresChangeEvent.insert,
schema: 'public',
- table: 'todos',
+ table: 'products',
+ filter: PostgresChangeFilter(
+ type: PostgresChangeFilterType.gt,
+ column: 'quantity',
+ value: 10,
+ ),
callback: (payload) => print(payload))
.subscribe();
```
</TabPanel>
</$Show>
-<$Show if="sdk:swfit">
+<$Show if="sdk:swift">
<TabPanel id="swift" label="Swift">
```swift
let myChannel = await supabase.channel("db-changes")
-let changes = await myChannel.postgresChange(AnyAction.self, schema: "public", table: "todos")
+let changes = await myChannel.postgresChange(
+ InsertAction.self,
+ schema: "public",
+ table: "products",
+ filter: .gt("quantity", value: 10)
+)
await myChannel.subscribe()
for await change in changes {
- switch change {
- case .insert(let action): print(action)
- case .update(let action): print(action)
- case .delete(let action): print(action)
- case .select(let action): print(action)
- }
+ print(change.record)
}
```
@@ -696,8 +1774,9 @@ for await change in changes {
```kotlin
val myChannel = supabase.channel("db-changes")
-val changes = myChannel.postgresChangeFlow<PostgresAction>(schema = "public") {
- table = "todos"
+val changes = myChannel.postgresChangeFlow<PostgresAction.Update>(schema = "public") {
+ table = "products"
+ filter = "quantity=gt.10"
}
changes
@@ -718,7 +1797,8 @@ myChannel.subscribe()
changes = supabase.channel('db-changes').on_postgres_changes(
"UPDATE",
schema="public",
- table="todos",
+ table="products",
+ filter="quantity=gt.10",
callback=lambda payload: print(payload)
)
.subscribe()
@@ -728,11 +1808,11 @@ changes = supabase.channel('db-changes').on_postgres_changes(
</$Show>
</Tabs>
-The channel name can be any string except 'realtime'.
+This filter uses Postgres's `>` filter, so it works for non-numeric types. Make sure to check the expected behavior of the compared data's type.
-### Listening to multiple changes
+### Greater than or equal to (`gte`)
-To listen to different events and schema/tables/filters combinations with the same channel:
+To listen to changes when a column's value in a table is greater than or equal to a client-specified value:
<Tabs
scrollable
@@ -743,46 +1823,69 @@ To listen to different events and schema/tables/filters combinations with the sa
>
<TabPanel id="js" label="JavaScript">
+<Tabs
+ scrollable
+ size="small"
+ type="underlined"
+ defaultActiveId="builder"
+ queryGroup="realtime-js-filter"
+>
+<TabPanel id="builder" label="Builder">
+
```js
const channel = supabase
- .channel('db-changes')
+ .channel('changes')
.on(
'postgres_changes',
{
- event: '*',
+ event: 'INSERT',
schema: 'public',
- table: 'messages',
+ table: 'products',
+ filter: postgresChangesFilter().gte('quantity', 10),
},
(payload) => console.log(payload)
)
+ .subscribe()
+```
+
+</TabPanel>
+<TabPanel id="string" label="Filter string">
+
+```js
+const channel = supabase
+ .channel('changes')
.on(
'postgres_changes',
{
event: 'INSERT',
schema: 'public',
- table: 'users',
+ table: 'products',
+ filter: 'quantity=gte.10',
},
(payload) => console.log(payload)
)
.subscribe()
```
+</TabPanel>
+</Tabs>
+
</TabPanel>
<$Show if="sdk:dart">
<TabPanel id="dart" label="Dart">
```dart
supabase
- .channel('db-changes')
- .onPostgresChanges(
- event: PostgresChangeEvent.all,
- schema: 'public',
- table: 'messages',
- callback: (payload) => print(payload))
+ .channel('changes')
.onPostgresChanges(
event: PostgresChangeEvent.insert,
schema: 'public',
- table: 'users',
+ table: 'products',
+ filter: PostgresChangeFilter(
+ type: PostgresChangeFilterType.gte,
+ column: 'quantity',
+ value: 10,
+ ),
callback: (payload) => print(payload))
.subscribe();
```
@@ -795,10 +1898,18 @@ supabase
```swift
let myChannel = await supabase.channel("db-changes")
-let messageChanges = await myChannel.postgresChange(AnyAction.self, schema: "public", table: "messages")
-let userChanges = await myChannel.postgresChange(InsertAction.self, schema: "public", table: "users")
+let changes = await myChannel.postgresChange(
+ InsertAction.self,
+ schema: "public",
+ table: "products",
+ filter: .gte("quantity", value: 10)
+)
await myChannel.subscribe()
+
+for await change in changes {
+ print(change.record)
+}
```
</TabPanel>
@@ -808,12 +1919,18 @@ await myChannel.subscribe()
```kotlin
val myChannel = supabase.channel("db-changes")
-val messageChanges = myChannel.postgresChangeFlow<PostgresAction>(schema = "public") {
- table = "messages"
-}
-val userChanges = myChannel.postgresChangeFlow<PostgresAction.Insert>(schema = "public") {
- table = "users"
+
+val changes = myChannel.postgresChangeFlow<PostgresAction.Update>(schema = "public") {
+ table = "products"
+ filter = "quantity=gte.10"
}
+
+changes
+ .onEach {
+ println(it.record)
+ }
+ .launchIn(yourCoroutineScope)
+
myChannel.subscribe()
```
@@ -824,25 +1941,24 @@ myChannel.subscribe()
```python
changes = supabase.channel('db-changes').on_postgres_changes(
- "*",
- schema="public",
- table="messages"
- callback=lambda payload: print(payload)
-).on_postgres_changes(
- "INSERT",
+ "UPDATE",
schema="public",
- table="users",
+ table="products",
+ filter="quantity=gte.10",
callback=lambda payload: print(payload)
-).subscribe()
+)
+.subscribe()
```
</TabPanel>
</$Show>
</Tabs>
-### Filtering for specific changes
+This filter uses Postgres's `>=` filter, so it works for non-numeric types. Make sure to check the expected behavior of the compared data's type.
+
+### Contained in list (in)
-Use the `filter` parameter for granular changes:
+To listen to changes when a column's value in a table equals any client-specified values:
<Tabs
scrollable
@@ -853,40 +1969,71 @@ Use the `filter` parameter for granular changes:
>
<TabPanel id="js" label="JavaScript">
+<Tabs
+ scrollable
+ size="small"
+ type="underlined"
+ defaultActiveId="builder"
+ queryGroup="realtime-js-filter"
+>
+<TabPanel id="builder" label="Builder">
+
```js
-const changes = supabase
- .channel('table-filter-changes')
+const channel = supabase
+ .channel('changes')
.on(
'postgres_changes',
{
event: 'INSERT',
schema: 'public',
- table: 'todos',
- filter: 'id=eq.1',
+ table: 'colors',
+ filter: postgresChangesFilter().in('name', ['red', 'blue', 'yellow']),
+ },
+ (payload) => console.log(payload)
+ )
+ .subscribe()
+```
+
+</TabPanel>
+<TabPanel id="string" label="Filter string">
+
+```js
+const channel = supabase
+ .channel('changes')
+ .on(
+ 'postgres_changes',
+ {
+ event: 'INSERT',
+ schema: 'public',
+ table: 'colors',
+ filter: 'name=in.(red,blue,yellow)',
},
(payload) => console.log(payload)
)
.subscribe()
```
+</TabPanel>
+</Tabs>
+
</TabPanel>
<$Show if="sdk:dart">
<TabPanel id="dart" label="Dart">
```dart
- supabase
- .channel('table-filter-changes')
- .onPostgresChanges(
- event: PostgresChangeEvent.insert,
- schema: 'public',
- table: 'todos',
- filter: PostgresChangeFilter(
- type: PostgresChangeFilterType.eq,
- column: 'id',
- value: 1,
- ),
- callback: (payload) => print(payload))
- .subscribe();
+supabase
+ .channel('changes')
+ .onPostgresChanges(
+ event: PostgresChangeEvent.insert,
+ schema: 'public',
+ table: 'colors',
+ filter: PostgresChangeFilter(
+ type: PostgresChangeFilterType.inFilter,
+ column: 'name',
+ value: ['red', 'blue', 'yellow'],
+ ),
+ callback: (payload) => print(payload))
+ .subscribe();
```
</TabPanel>
@@ -900,8 +2047,8 @@ let myChannel = await supabase.channel("db-changes")
let changes = await myChannel.postgresChange(
InsertAction.self,
schema: "public",
- table: "todos",
- filter: .eq("id", value: 1)
+ table: "products",
+ filter: .in("name", values: ["red", "blue", "yellow"])
)
await myChannel.subscribe()
@@ -919,9 +2066,9 @@ for await change in changes {
```kotlin
val myChannel = supabase.channel("db-changes")
-val changes = myChannel.postgresChangeFlow<PostgresAction.Insert>(schema = "public") {
- table = "todos"
- filter = "id=eq.1"
+val changes = myChannel.postgresChangeFlow<PostgresAction.Update>(schema = "public") {
+ table = "products"
+ filter = "name=in.(red,blue,yellow)"
}
changes
@@ -940,10 +2087,10 @@ myChannel.subscribe()
```python
changes = supabase.channel('db-changes').on_postgres_changes(
- "INSERT",
+ "UPDATE",
schema="public",
- table="todos",
- filter="id=eq.1",
+ table="products",
+ filter="name=in.(red,blue,yellow)",
callback=lambda payload: print(payload)
)
.subscribe()
@@ -953,13 +2100,11 @@ changes = supabase.channel('db-changes').on_postgres_changes(
</$Show>
</Tabs>
-## Available filters
-
-Realtime offers filters so you can specify the data your client receives at a more granular level.
+This filter uses Postgres's `= ANY`. Realtime allows a maximum of 100 values for this filter.
-### Equal to (`eq`)
+### Pattern matching (`like`, `ilike`)
-To listen to changes when a column's value in a table equals a client-specified value:
+To listen to changes when a text column matches a pattern, use `like` (case-sensitive) or `ilike` (case-insensitive). Use `%` to match any sequence of characters and `_` to match a single character.
<Tabs
scrollable
@@ -970,22 +2115,54 @@ To listen to changes when a column's value in a table equals a client-specified
>
<TabPanel id="js" label="JavaScript">
+<Tabs
+ scrollable
+ size="small"
+ type="underlined"
+ defaultActiveId="builder"
+ queryGroup="realtime-js-filter"
+>
+<TabPanel id="builder" label="Builder">
+
```js
const channel = supabase
.channel('changes')
.on(
'postgres_changes',
{
- event: 'UPDATE',
+ event: 'INSERT',
schema: 'public',
- table: 'messages',
- filter: 'body=eq.hey',
+ table: 'articles',
+ // matches "Breaking News", "BREAKING", ...
+ filter: postgresChangesFilter().ilike('title', '%breaking%'),
+ },
+ (payload) => console.log(payload)
+ )
+ .subscribe()
+```
+
+</TabPanel>
+<TabPanel id="string" label="Filter string">
+
+```js
+const channel = supabase
+ .channel('changes')
+ .on(
+ 'postgres_changes',
+ {
+ event: 'INSERT',
+ schema: 'public',
+ table: 'articles',
+ filter: 'title=ilike.%breaking%', // matches "Breaking News", "BREAKING", ...
},
(payload) => console.log(payload)
)
.subscribe()
```
+</TabPanel>
+</Tabs>
+
</TabPanel>
<$Show if="sdk:dart">
<TabPanel id="dart" label="Dart">
@@ -994,13 +2171,13 @@ const channel = supabase
supabase
.channel('changes')
.onPostgresChanges(
- event: PostgresChangeEvent.update,
+ event: PostgresChangeEvent.insert,
schema: 'public',
- table: 'messages',
+ table: 'articles',
filter: PostgresChangeFilter(
- type: PostgresChangeFilterType.eq,
- column: 'body',
- value: 'hey',
+ type: PostgresChangeFilterType.ilike,
+ column: 'title',
+ value: '%breaking%',
),
callback: (payload) => print(payload))
.subscribe();
@@ -1015,10 +2192,10 @@ supabase
let myChannel = await supabase.channel("db-changes")
let changes = await myChannel.postgresChange(
- UpdateAction.self,
+ InsertAction.self,
schema: "public",
- table: "messages",
- filter: .eq("body", value: "hey")
+ table: "articles",
+ filter: .ilike("title", value: "%breaking%")
)
await myChannel.subscribe()
@@ -1036,9 +2213,9 @@ for await change in changes {
```kotlin
val myChannel = supabase.channel("db-changes")
-val changes = myChannel.postgresChangeFlow<PostgresAction.Update>(schema = "public") {
- table = "messages"
- filter = "body=eq.hey"
+val changes = myChannel.postgresChangeFlow<PostgresAction.Insert>(schema = "public") {
+ table = "articles"
+ filter = "title=ilike.%breaking%"
}
changes
@@ -1057,10 +2234,10 @@ myChannel.subscribe()
```python
changes = supabase.channel('db-changes').on_postgres_changes(
- "UPDATE",
+ "INSERT",
schema="public",
- table="messages",
- filter="body=eq.hey",
+ table="articles",
+ filter="title=ilike.%breaking%",
callback=lambda payload: print(payload)
)
.subscribe()
@@ -1070,11 +2247,11 @@ changes = supabase.channel('db-changes').on_postgres_changes(
</$Show>
</Tabs>
-This filter uses Postgres's `=` filter.
+`like` uses Postgres's `LIKE` and `ilike` uses `ILIKE`. Both require a text-compatible column. The examples above use `ilike`; swap in `like` for case-sensitive matching—usage is otherwise identical.
-### Not equal to (`neq`)
+### Regular expression matching (`match`, `imatch`)
-To listen to changes when a column's value in a table does not equal a client-specified value:
+To listen to changes when a text column matches a POSIX regular expression, use `match` (case-sensitive) or `imatch` (case-insensitive).
<Tabs
scrollable
@@ -1085,6 +2262,15 @@ To listen to changes when a column's value in a table does not equal a client-sp
>
<TabPanel id="js" label="JavaScript">
+<Tabs
+ scrollable
+ size="small"
+ type="underlined"
+ defaultActiveId="builder"
+ queryGroup="realtime-js-filter"
+>
+<TabPanel id="builder" label="Builder">
+
```js
const channel = supabase
.channel('changes')
@@ -1093,14 +2279,37 @@ const channel = supabase
{
event: 'INSERT',
schema: 'public',
- table: 'messages',
- filter: 'body=neq.bye',
+ table: 'posts',
+ // matches "post-1", "post-42", ...
+ filter: postgresChangesFilter().match('slug', '^post-\\d+$'),
+ },
+ (payload) => console.log(payload)
+ )
+ .subscribe()
+```
+
+</TabPanel>
+<TabPanel id="string" label="Filter string">
+
+```js
+const channel = supabase
+ .channel('changes')
+ .on(
+ 'postgres_changes',
+ {
+ event: 'INSERT',
+ schema: 'public',
+ table: 'posts',
+ filter: 'slug=match.^post-\\d+$', // matches "post-1", "post-42", ...
},
(payload) => console.log(payload)
)
.subscribe()
```
+</TabPanel>
+</Tabs>
+
</TabPanel>
<$Show if="sdk:dart">
<TabPanel id="dart" label="Dart">
@@ -1111,11 +2320,11 @@ supabase
.onPostgresChanges(
event: PostgresChangeEvent.insert,
schema: 'public',
- table: 'messages',
+ table: 'posts',
filter: PostgresChangeFilter(
- type: PostgresChangeFilterType.neq,
- column: 'body',
- value: 'bye',
+ type: PostgresChangeFilterType.match,
+ column: 'slug',
+ value: r'^post-\d+$',
),
callback: (payload) => print(payload))
.subscribe();
@@ -1130,10 +2339,10 @@ supabase
let myChannel = await supabase.channel("db-changes")
let changes = await myChannel.postgresChange(
- UpdateAction.self,
+ InsertAction.self,
schema: "public",
- table: "messages",
- filter: .neq("body", value: "hey")
+ table: "posts",
+ filter: .match("slug", value: "^post-\\d+$")
)
await myChannel.subscribe()
@@ -1149,11 +2358,11 @@ for await change in changes {
<TabPanel id="kotlin" label="Kotlin">
```kotlin
-val myChannel = supabase.realtime.createChannel("db-changes")
+val myChannel = supabase.channel("db-changes")
-val changes = myChannel.postgresChangeFlow<PostgresAction.Update>(schema = "public") {
- table = "messages"
- filter = "body=neq.bye"
+val changes = myChannel.postgresChangeFlow<PostgresAction.Insert>(schema = "public") {
+ table = "posts"
+ filter = "slug=match.^post-\\d+$"
}
changes
@@ -1162,8 +2371,7 @@ changes
}
.launchIn(yourCoroutineScope)
-supabase.realtime.connect()
-myChannel.join()
+myChannel.subscribe()
```
</TabPanel>
@@ -1175,8 +2383,8 @@ myChannel.join()
changes = supabase.channel('db-changes').on_postgres_changes(
"INSERT",
schema="public",
- table="messages",
- filter="body=neq.bye",
+ table="posts",
+ filter="slug=match.^post-\\d+$",
callback=lambda payload: print(payload)
)
.subscribe()
@@ -1186,11 +2394,11 @@ changes = supabase.channel('db-changes').on_postgres_changes(
</$Show>
</Tabs>
-This filter uses Postgres's `!=` filter.
+`match` uses Postgres's `~` operator and `imatch` uses `~*`. Both require a text-compatible column, and the pattern is validated when you subscribe. The examples above use `match`; swap in `imatch` for case-insensitive matching—usage is otherwise identical.
-### Less than (`lt`)
+### Null and boolean checks (`is`)
-To listen to changes when a column's value in a table is less than a client-specified value:
+To listen to changes when a column `IS` `null`, `true`, `false`, or `unknown`, use `is`. `is.null` works on any column type; `is.true`, `is.false`, and `is.unknown` require a boolean column.
<Tabs
scrollable
@@ -1201,22 +2409,54 @@ To listen to changes when a column's value in a table is less than a client-spec
>
<TabPanel id="js" label="JavaScript">
+<Tabs
+ scrollable
+ size="small"
+ type="underlined"
+ defaultActiveId="builder"
+ queryGroup="realtime-js-filter"
+>
+<TabPanel id="builder" label="Builder">
+
```js
const channel = supabase
.channel('changes')
.on(
'postgres_changes',
{
- event: 'INSERT',
+ event: 'UPDATE',
schema: 'public',
- table: 'profiles',
- filter: 'age=lt.65',
+ table: 'todos',
+ // only rows that are not yet completed
+ filter: postgresChangesFilter().is('completed_at', null),
+ },
+ (payload) => console.log(payload)
+ )
+ .subscribe()
+```
+
+</TabPanel>
+<TabPanel id="string" label="Filter string">
+
+```js
+const channel = supabase
+ .channel('changes')
+ .on(
+ 'postgres_changes',
+ {
+ event: 'UPDATE',
+ schema: 'public',
+ table: 'todos',
+ filter: 'completed_at=is.null', // only rows that are not yet completed
},
(payload) => console.log(payload)
)
.subscribe()
```
+</TabPanel>
+</Tabs>
+
</TabPanel>
<$Show if="sdk:dart">
<TabPanel id="dart" label="Dart">
@@ -1225,13 +2465,13 @@ const channel = supabase
supabase
.channel('changes')
.onPostgresChanges(
- event: PostgresChangeEvent.insert,
+ event: PostgresChangeEvent.update,
schema: 'public',
- table: 'profiles',
+ table: 'todos',
filter: PostgresChangeFilter(
- type: PostgresChangeFilterType.lt,
- column: 'age',
- value: 65,
+ type: PostgresChangeFilterType.isFilter,
+ column: 'completed_at',
+ value: null,
),
callback: (payload) => print(payload))
.subscribe();
@@ -1246,10 +2486,10 @@ supabase
let myChannel = await supabase.channel("db-changes")
let changes = await myChannel.postgresChange(
- InsertAction.self,
+ UpdateAction.self,
schema: "public",
- table: "profiles",
- filter: .lt("age", value: 65)
+ table: "todos",
+ filter: .is("completed_at", value: .null)
)
await myChannel.subscribe()
@@ -1267,9 +2507,9 @@ for await change in changes {
```kotlin
val myChannel = supabase.channel("db-changes")
-val changes = myChannel.postgresChangeFlow<PostgresAction.Insert>(schema = "public") {
- table = "profiles"
- filter = "age=lt.65"
+val changes = myChannel.postgresChangeFlow<PostgresAction.Update>(schema = "public") {
+ table = "todos"
+ filter = "completed_at=is.null"
}
changes
@@ -1288,10 +2528,10 @@ myChannel.subscribe()
```python
changes = supabase.channel('db-changes').on_postgres_changes(
- "INSERT",
+ "UPDATE",
schema="public",
- table="profiles",
- filter="age=lt.65",
+ table="todos",
+ filter="completed_at=is.null",
callback=lambda payload: print(payload)
)
.subscribe()
@@ -1301,11 +2541,11 @@ changes = supabase.channel('db-changes').on_postgres_changes(
</$Show>
</Tabs>
-This filter uses Postgres's `<` filter, so it works for non-numeric types. Make sure to check the expected behavior of the compared data's type.
+This filter uses Postgres's `IS` operator.
-### Less than or equal to (`lte`)
+### Distinct from (`isdistinct`)
-To listen to changes when a column's value in a table is less than or equal to a client-specified value:
+`isdistinct` is a NULL-safe inequality (`IS DISTINCT FROM`). Unlike `neq`, it treats `null` as a comparable value, so a `null` column is considered distinct from a non-null value.
<Tabs
scrollable
@@ -1316,6 +2556,35 @@ To listen to changes when a column's value in a table is less than or equal to a
>
<TabPanel id="js" label="JavaScript">
+<Tabs
+ scrollable
+ size="small"
+ type="underlined"
+ defaultActiveId="builder"
+ queryGroup="realtime-js-filter"
+>
+<TabPanel id="builder" label="Builder">
+
+```js
+const channel = supabase
+ .channel('changes')
+ .on(
+ 'postgres_changes',
+ {
+ event: 'UPDATE',
+ schema: 'public',
+ table: 'orders',
+ // includes rows where status is null
+ filter: postgresChangesFilter().isDistinct('status', 'shipped'),
+ },
+ (payload) => console.log(payload)
+ )
+ .subscribe()
+```
+
+</TabPanel>
+<TabPanel id="string" label="Filter string">
+
```js
const channel = supabase
.channel('changes')
@@ -1324,14 +2593,17 @@ const channel = supabase
{
event: 'UPDATE',
schema: 'public',
- table: 'profiles',
- filter: 'age=lte.65',
+ table: 'orders',
+ filter: 'status=isdistinct.shipped', // includes rows where status is null
},
(payload) => console.log(payload)
)
.subscribe()
```
+</TabPanel>
+</Tabs>
+
</TabPanel>
<$Show if="sdk:dart">
<TabPanel id="dart" label="Dart">
@@ -1340,13 +2612,13 @@ const channel = supabase
supabase
.channel('changes')
.onPostgresChanges(
- event: PostgresChangeEvent.insert,
+ event: PostgresChangeEvent.update,
schema: 'public',
- table: 'profiles',
+ table: 'orders',
filter: PostgresChangeFilter(
- type: PostgresChangeFilterType.lte,
- column: 'age',
- value: 65,
+ type: PostgresChangeFilterType.isDistinct,
+ column: 'status',
+ value: 'shipped',
),
callback: (payload) => print(payload))
.subscribe();
@@ -1361,10 +2633,10 @@ supabase
let myChannel = await supabase.channel("db-changes")
let changes = await myChannel.postgresChange(
- InsertAction.self,
+ UpdateAction.self,
schema: "public",
- table: "profiles",
- filter: .lte("age", value: 65)
+ table: "orders",
+ filter: .isDistinct("status", value: "shipped")
)
await myChannel.subscribe()
@@ -1383,8 +2655,8 @@ for await change in changes {
val myChannel = supabase.channel("db-changes")
val changes = myChannel.postgresChangeFlow<PostgresAction.Update>(schema = "public") {
- table = "profiles"
- filter = "age=lte.65"
+ table = "orders"
+ filter = "status=isdistinct.shipped"
}
changes
@@ -1405,8 +2677,8 @@ myChannel.subscribe()
changes = supabase.channel('db-changes').on_postgres_changes(
"UPDATE",
schema="public",
- table="profiles",
- filter="age=lte.65",
+ table="orders",
+ filter="status=isdistinct.shipped",
callback=lambda payload: print(payload)
)
.subscribe()
@@ -1416,11 +2688,9 @@ changes = supabase.channel('db-changes').on_postgres_changes(
</$Show>
</Tabs>
-This filter uses Postgres' `<=` filter, so it works for non-numeric types. Make sure to check the expected behavior of the compared data's type.
-
-### Greater than (`gt`)
+### Negating a filter (`not`)
-To listen to changes when a column's value in a table is greater than a client-specified value:
+Prefix any operator with `not.` to invert it — for example `not.in`, `not.is`, or `not.like`.
<Tabs
scrollable
@@ -1431,37 +2701,72 @@ To listen to changes when a column's value in a table is greater than a client-s
>
<TabPanel id="js" label="JavaScript">
+<Tabs
+ scrollable
+ size="small"
+ type="underlined"
+ defaultActiveId="builder"
+ queryGroup="realtime-js-filter"
+>
+<TabPanel id="builder" label="Builder">
+
```js
const channel = supabase
.channel('changes')
.on(
'postgres_changes',
{
- event: 'INSERT',
+ event: '*',
schema: 'public',
- table: 'products',
- filter: 'quantity=gt.10',
+ table: 'posts',
+ // anything except drafts and archived
+ filter: postgresChangesFilter().not('status', 'in', ['draft', 'archived']),
+ },
+ (payload) => console.log(payload)
+ )
+ .subscribe()
+```
+
+</TabPanel>
+<TabPanel id="string" label="Filter string">
+
+```js
+const channel = supabase
+ .channel('changes')
+ .on(
+ 'postgres_changes',
+ {
+ event: '*',
+ schema: 'public',
+ table: 'posts',
+ filter: 'status=not.in.(draft,archived)', // anything except drafts and archived
},
(payload) => console.log(payload)
)
.subscribe()
```
+</TabPanel>
+</Tabs>
+
</TabPanel>
<$Show if="sdk:dart">
<TabPanel id="dart" label="Dart">
+Set `negate: true` on a `PostgresChangeFilter` to apply the `not.` prefix.
+
```dart
supabase
.channel('changes')
.onPostgresChanges(
- event: PostgresChangeEvent.insert,
+ event: PostgresChangeEvent.all,
schema: 'public',
- table: 'products',
+ table: 'posts',
filter: PostgresChangeFilter(
- type: PostgresChangeFilterType.gt,
- column: 'quantity',
- value: 10,
+ type: PostgresChangeFilterType.inFilter,
+ column: 'status',
+ value: ['draft', 'archived'],
+ negate: true,
),
callback: (payload) => print(payload))
.subscribe();
@@ -1472,21 +2777,19 @@ supabase
<$Show if="sdk:swift">
<TabPanel id="swift" label="Swift">
+Wrap any single-condition filter in `.not(...)`.
+
```swift
let myChannel = await supabase.channel("db-changes")
let changes = await myChannel.postgresChange(
- InsertAction.self,
+ AnyAction.self,
schema: "public",
- table: "products",
- filter: .gt("quantity", value: 10)
+ table: "posts",
+ filter: .not(.in("status", values: ["draft", "archived"]))
)
await myChannel.subscribe()
-
-for await change in changes {
- print(change.record)
-}
```
</TabPanel>
@@ -1497,9 +2800,9 @@ for await change in changes {
```kotlin
val myChannel = supabase.channel("db-changes")
-val changes = myChannel.postgresChangeFlow<PostgresAction.Update>(schema = "public") {
- table = "products"
- filter = "quantity=gt.10"
+val changes = myChannel.postgresChangeFlow<PostgresAction>(schema = "public") {
+ table = "posts"
+ filter = "status=not.in.(draft,archived)"
}
changes
@@ -1518,10 +2821,10 @@ myChannel.subscribe()
```python
changes = supabase.channel('db-changes').on_postgres_changes(
- "UPDATE",
+ "*",
schema="public",
- table="products",
- filter="quantity=gt.10",
+ table="posts",
+ filter="status=not.in.(draft,archived)",
callback=lambda payload: print(payload)
)
.subscribe()
@@ -1531,11 +2834,9 @@ changes = supabase.channel('db-changes').on_postgres_changes(
</$Show>
</Tabs>
-This filter uses Postgres's `>` filter, so it works for non-numeric types. Make sure to check the expected behavior of the compared data's type.
-
-### Greater than or equal to (`gte`)
+### Combining filters with `AND`
-To listen to changes when a column's value in a table is greater than or equal to a client-specified value:
+Combine multiple conditions by separating them with commas. All conditions must match (logical `AND`). You can only combine conditions with `AND` — `OR` is not supported.
<Tabs
scrollable
@@ -1546,6 +2847,17 @@ To listen to changes when a column's value in a table is greater than or equal t
>
<TabPanel id="js" label="JavaScript">
+<Tabs
+ scrollable
+ size="small"
+ type="underlined"
+ defaultActiveId="builder"
+ queryGroup="realtime-js-filter"
+>
+<TabPanel id="builder" label="Builder">
+
+The builder composes conditions and escapes reserved characters for you.
+
```js
const channel = supabase
.channel('changes')
@@ -1554,30 +2866,62 @@ const channel = supabase
{
event: 'INSERT',
schema: 'public',
- table: 'products',
- filter: 'quantity=gte.10',
+ table: 'orders',
+ // amount > 100 AND status = "open"
+ filter: postgresChangesFilter().gt('amount', 100).eq('status', 'open'),
+ },
+ (payload) => console.log(payload)
+ )
+ .subscribe()
+```
+
+</TabPanel>
+<TabPanel id="string" label="Filter string">
+
+```js
+const channel = supabase
+ .channel('changes')
+ .on(
+ 'postgres_changes',
+ {
+ event: 'INSERT',
+ schema: 'public',
+ table: 'orders',
+ filter: 'amount=gt.100,status=eq.open', // amount > 100 AND status = "open"
},
(payload) => console.log(payload)
)
.subscribe()
```
+</TabPanel>
+</Tabs>
+
</TabPanel>
<$Show if="sdk:dart">
<TabPanel id="dart" label="Dart">
+Pass a list of filters to `filters` to combine them with `AND`.
+
```dart
supabase
.channel('changes')
.onPostgresChanges(
event: PostgresChangeEvent.insert,
schema: 'public',
- table: 'products',
- filter: PostgresChangeFilter(
- type: PostgresChangeFilterType.gte,
- column: 'quantity',
- value: 10,
- ),
+ table: 'orders',
+ filters: [
+ PostgresChangeFilter(
+ type: PostgresChangeFilterType.gt,
+ column: 'amount',
+ value: 100,
+ ),
+ PostgresChangeFilter(
+ type: PostgresChangeFilterType.eq,
+ column: 'status',
+ value: 'open',
+ ),
+ ],
callback: (payload) => print(payload))
.subscribe();
```
@@ -1587,21 +2931,22 @@ supabase
<$Show if="sdk:swift">
<TabPanel id="swift" label="Swift">
+Use `.and([...])` to combine multiple conditions.
+
```swift
let myChannel = await supabase.channel("db-changes")
let changes = await myChannel.postgresChange(
InsertAction.self,
schema: "public",
- table: "products",
- filter: .gte("quantity", value: 10)
+ table: "orders",
+ filter: .and([
+ .gt("amount", value: 100),
+ .eq("status", value: "open"),
+ ])
)
await myChannel.subscribe()
-
-for await change in changes {
- print(change.record)
-}
```
</TabPanel>
@@ -1612,9 +2957,9 @@ for await change in changes {
```kotlin
val myChannel = supabase.channel("db-changes")
-val changes = myChannel.postgresChangeFlow<PostgresAction.Update>(schema = "public") {
- table = "products"
- filter = "quantity=gte.10"
+val changes = myChannel.postgresChangeFlow<PostgresAction.Insert>(schema = "public") {
+ table = "orders"
+ filter = "amount=gt.100,status=eq.open"
}
changes
@@ -1633,10 +2978,10 @@ myChannel.subscribe()
```python
changes = supabase.channel('db-changes').on_postgres_changes(
- "UPDATE",
+ "INSERT",
schema="public",
- table="products",
- filter="quantity=gte.10",
+ table="orders",
+ filter="amount=gt.100,status=eq.open",
callback=lambda payload: print(payload)
)
.subscribe()
@@ -1646,11 +2991,17 @@ changes = supabase.channel('db-changes').on_postgres_changes(
</$Show>
</Tabs>
-This filter uses Postgres's `>=` filter, so it works for non-numeric types. Make sure to check the expected behavior of the compared data's type.
+<Admonition type="note">
-### Contained in list (in)
+Values that contain reserved characters (`,`, `(`, `)`, `"`, or `\`) must be double-quoted PostgREST-style so the server doesn't read them as condition or list boundaries — for example `name=eq."Doe, Jane"`. The `postgresChangesFilter()` builder (JavaScript), `PostgresChangeFilter` (Dart), and `RealtimePostgresFilter` (Swift) apply this quoting for you.
-To listen to changes when a column's value in a table equals any client-specified values:
+</Admonition>
+
+## Selecting specific columns
+
+By default each change event contains the full row. Use `select` to receive only a subset of columns instead. This reduces payload size and the data transferred per event, which is especially useful for tables with large `bytea`, `jsonb`, or `text` columns.
+
+The listed columns must be selectable by the subscribing role, and the table's primary key is always included so you can identify the row. `select` requires an explicit `schema` and `table` — it's not supported on wildcard subscriptions.
<Tabs
scrollable
@@ -1667,10 +3018,10 @@ const channel = supabase
.on(
'postgres_changes',
{
- event: 'INSERT',
+ event: '*',
schema: 'public',
- table: 'colors',
- filter: 'name=in.(red, blue, yellow)',
+ table: 'profiles',
+ select: ['id', 'username'], // payload.new only contains { id, username }
},
(payload) => console.log(payload)
)
@@ -1685,14 +3036,10 @@ const channel = supabase
supabase
.channel('changes')
.onPostgresChanges(
- event: PostgresChangeEvent.insert,
+ event: PostgresChangeEvent.all,
schema: 'public',
- table: 'colors',
- filter: PostgresChangeFilter(
- type: PostgresChangeFilterType.inFilter,
- column: 'name',
- value: ['red', 'blue', 'yellow'],
- ),
+ table: 'profiles',
+ select: ['id', 'username'],
callback: (payload) => print(payload))
.subscribe();
```
@@ -1706,63 +3053,19 @@ supabase
let myChannel = await supabase.channel("db-changes")
let changes = await myChannel.postgresChange(
- InsertAction.self,
+ AnyAction.self,
schema: "public",
- table: "products",
- filter: .in("name", values: ["red", "blue", "yellow"])
+ table: "profiles",
+ select: ["id", "username"]
)
await myChannel.subscribe()
-
-for await change in changes {
- print(change.record)
-}
-```
-
-</TabPanel>
-</$Show>
-<$Show if="sdk:kotlin">
-<TabPanel id="kotlin" label="Kotlin">
-
-```kotlin
-val myChannel = supabase.channel("db-changes")
-
-val changes = myChannel.postgresChangeFlow<PostgresAction.Update>(schema = "public") {
- table = "products"
- filter = "name=in.(red, blue, yellow)"
-}
-
-changes
- .onEach {
- println(it.record)
- }
- .launchIn(yourCoroutineScope)
-
-myChannel.subscribe()
-```
-
-</TabPanel>
-</$Show>
-<$Show if="sdk:python">
-<TabPanel id="python" label="Python">
-
-```python
-changes = supabase.channel('db-changes').on_postgres_changes(
- "UPDATE",
- schema="public",
- table="products",
- filter="name=in.(red, blue, yellow)",
- callback=lambda payload: print(payload)
-)
-.subscribe()
```
</TabPanel>
</$Show>
</Tabs>
-This filter uses Postgres's `= ANY`. Realtime allows a maximum of 100 values for this filter.
-
## Receiving `old` records
By default, only `new` record changes are sent but if you want to receive the `old` record (previous values) whenever you `UPDATE` or `DELETE` a record, you can set the `replica identity` of your table to `full`:
@@ -1875,7 +3178,7 @@ let changes = await myChannel.postgresChange(
UpdateAction.self,
schema: "public",
table: "products",
- filter: "name=in.(red, blue, yellow)"
+ filter: "name=in.(red,blue,yellow)"
)
await myChannel.subscribe()
@@ -1900,7 +3203,7 @@ val myChannel = supabase.channel("db-changes")
val changes = myChannel.postgresChangeFlow<PostgresAction.Update>(schema = "public") {
table = "products"
- filter = "name=in.(red, blue, yellow)"
+ filter = "name=in.(red,blue,yellow)"
}
changes
@@ -1924,7 +3227,7 @@ changes = supabase.channel('db-changes').on_postgres_changes(
"UPDATE",
schema="public",
table="products",
- filter="name=in.(red, blue, yellow)",
+ filter="name=in.(red,blue,yellow)",
callback=lambda payload: print(payload)
)
.subscribe()
@@ -1934,92 +3237,29 @@ changes = supabase.channel('db-changes').on_postgres_changes(
</$Show>
</Tabs>
-### Refreshed tokens
-
-You will need to refresh tokens on your own, but once generated, you can pass them to Realtime.
-
-<Tabs
- scrollable
- size="small"
- type="underlined"
- defaultActiveId="js"
- queryGroup="language"
->
-<TabPanel id="js" label="JavaScript">
-
-For example, if you're using the `supabase-js` `v2` client then you can pass your token like this:
-
-```js
-// Client setup
-
-supabase.realtime.setAuth('fresh-token')
-```
-
-</TabPanel>
-<$Show if="sdk:dart">
-<TabPanel id="dart" label="Dart">
-
-```dart
-supabase.realtime.setAuth('fresh-token');
-```
-
-</TabPanel>
-</$Show>
-<$Show if="sdk:swift">
-<TabPanel id="swift" label="Swift">
-
-```swift
-await supabase.realtime.setAuth("fresh-token")
-```
-
-</TabPanel>
-</$Show>
-<$Show if="sdk:kotlin">
-<TabPanel id="kotlin" label="Kotlin">
-
-In Kotlin, you have to update the token manually per channel:
-
-```kotlin
-myChannel.updateAuth("fresh-token")
-```
-
-</TabPanel>
-</$Show>
-<$Show if="sdk:python">
-<TabPanel id="python" label="Python">
-
-```python
-supabase.realtime.set_auth('fresh-token')
-```
-
-</TabPanel>
-</$Show>
-</Tabs>
-
## Limitations
### Delete events are not filterable
You can't filter Delete events when tracking Postgres Changes. This limitation is due to the way changes are pulled from Postgres.
-### Spaces in table names
+## Scaling Postgres Changes
-Realtime currently does not work when table names contain spaces.
+Postgres Changes authorizes every event against each subscriber. When you make a single change to a table with 100 subscribed users, Realtime performs 100 authorization checks — one per user — so throughput scales with the number of subscribers, not the write rate. Changes are also processed on a single thread to preserve their order, which means larger compute add-ons don't meaningfully increase Postgres Changes throughput.
-### Database instance and realtime performance
+For most applications this is plenty. To get the best performance:
-Realtime systems usually require forethought because of their scaling dynamics. For the `Postgres Changes` feature, every change event must be checked to see if the subscribed user has access. For instance, if you have 100 users subscribed to a table where you make a single insert, it will then trigger 100 "reads": one for each user.
+- Use [filters](#available-filters) and [column selection](#selecting-specific-columns) to send each client only the events and columns it needs.
+- Keep authorization cheap by writing , indexed [RLS policies](/docs/guides/database/postgres/row-level-security).
-There can be a database bottleneck which limits message throughput. If your database cannot authorize the changes rapidly enough, the changes will be delayed until you receive a timeout.
+Use the estimator below to gauge the maximum throughput for your instance, and run your own benchmarks to confirm it fits your use case:
-Database changes are processed on a single thread to maintain the change order. That means compute upgrades don't have a large effect on the performance of Postgres change subscriptions. You can estimate the expected maximum throughput for your database below.
-
-If you are using Postgres Changes at scale, you should consider using separate "public" table without RLS and filters. Alternatively, you can use Realtime server-side only and then re-stream the changes to your clients using a Realtime Broadcast.
+<RealtimeLimitsEstimator />
-Enter your database settings to estimate the maximum throughput for your instance:
+<Admonition type="tip">
-<RealtimeLimitsEstimator />
+If you expect more than ~3,000 concurrent subscribers on the same changes, use [Broadcast to stream database changes](/docs/guides/realtime/subscribing-to-database-changes#using-broadcast) instead. Broadcast sends each change once and fans it out to all subscribers, so it scales to far higher connection counts than per-subscriber authorization allows.
-Don't forget to run your own benchmarks to make sure that the performance is acceptable for your use case.
+</Admonition>
-We are making many improvements to Realtime's Postgres Changes. If you are uncertain about the performance of your use case, reach out using [Support Form](/dashboard/support/new) and we will be happy to help you. We have a team of engineers that can advise you on the best solution for your use-case.
+If you're unsure which approach fits your use case, reach out through the [Support Form](/dashboard/support/new) — our engineers are happy to help you find the best solution.
diff --git a/apps/docs/internals/markdown-schema/RealtimeLimitsEstimator.ts b/apps/docs/internals/markdown-schema/RealtimeLimitsEstimator.ts
index 7d07d8dc8a4..eda16e8c79e 100644
--- a/apps/docs/internals/markdown-schema/RealtimeLimitsEstimator.ts
+++ b/apps/docs/internals/markdown-schema/RealtimeLimitsEstimator.ts
@@ -6,7 +6,6 @@ import throughputTable from '../../data/realtime/throughput.json'
type Row = {
computeAddOn: string
- filters: boolean
rls: boolean
concurrency: number
maxDBChanges: number
@@ -27,7 +26,7 @@ ${dividerRow}
${rows
.map(
(l) =>
- `| ${l.filters ? 'Yes' : 'No'} | ${l.rls ? 'Yes' : 'No'} | ${l.concurrency.toLocaleString()} | ${l.maxDBChanges} | ${l.maxMessagesPerClient} | ${l.totalMessagesPerSecond.toLocaleString()} | ${l.p95Latency}ms |`
+ `| ${l.rls ? 'Yes' : 'No'} | ${l.concurrency.toLocaleString()} | ${l.maxDBChanges} | ${l.maxMessagesPerClient} | ${l.totalMessagesPerSecond.toLocaleString()} | ${l.p95Latency}ms |`
)
.join('\n')}`
}