Database Subscriptions

Subscribe to live changes on any database table. Aerostack’s ChangeTracker polls your database every 200ms and broadcasts INSERT, UPDATE, and DELETE events to all subscribers — no sdk.socket.emit() required.

How it works

Use a bare table name (no slashes) as the channel topic. Aerostack maps this to the table/{name}/{projectId} internal topic and activates ChangeTracker for it.

// This subscribes to ALL changes on the `orders` table
const channel = realtime.channel('orders')

Listen for changes

import { useAerostack } from '@aerostack/react'

function OrderDashboard() {
  const { realtime } = useAerostack()
  const [orders, setOrders] = useState([])

  useEffect(() => {
    const channel = realtime.channel('orders')

    channel
      .on('INSERT', ({ data }) => {
        setOrders(prev => [...prev, data])
      })
      .on('UPDATE', ({ data }) => {
        setOrders(prev => prev.map(o => o.id === data.id ? data : o))
      })
      .on('DELETE', ({ data }) => {
        setOrders(prev => prev.filter(o => o.id !== data.id))
      })
      .subscribe()

    return () => channel.unsubscribe()
  }, [realtime])
}

Listen to all events with *

channel.on('*', ({ operation, data, old }) => {
  console.log(`${operation} on orders:`, data)
  // operation: 'INSERT' | 'UPDATE' | 'DELETE'
  // old: previous row state (for UPDATE/DELETE)
})

Event payload shape

interface RealtimePayload {
  type: 'db_change'
  topic: string          // 'table/orders/<projectId>'
  operation: 'INSERT' | 'UPDATE' | 'DELETE'
  data: Record<string, any>   // new row values
  old?: Record<string, any>   // previous values (UPDATE/DELETE only)
  timestamp: number
}

Filter by column value

Note

Column-level filtering is on the roadmap. Currently all row changes on the subscribed table are broadcast.

Server-side: no extra code needed

Your server just runs normal SQL queries. ChangeTracker handles the rest:

// Workers / Node.js — just run your SQL
await sdk.db.query(
  'UPDATE orders SET status = ? WHERE id = ?',
  ['shipped', orderId]
)
// → All clients subscribed to 'orders' receive an UPDATE event automatically

Language support

React

const channel = realtime.channel('orders')
channel.on('INSERT', ({ data }) => console.log('New order:', data))
channel.subscribe()

Node.js

const channel = realtime.channel('orders')
channel.on('INSERT', ({ data }) => console.log('New order:', data))
channel.subscribe()

Go

ch := realtime.Channel("orders")
ch.On("INSERT", func(payload RealtimePayload) {
    fmt.Println("New order:", payload.Data)
})
ch.Subscribe()

Python

channel = realtime.channel("orders")
channel.on("INSERT", lambda payload: print("New order:", payload.data))
channel.subscribe()

Flutter

final channel = realtime.channel('orders');
channel.on('INSERT', (payload) => print('New order: ${payload.data}'));
channel.subscribe();

See the Live Order Dashboard example for a complete working implementation.