FeaturesRealtimeDatabase Subscriptions

Database Subscriptions

Subscribe to live changes on any D1 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'
import { useEffect, useState } from '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

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

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

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

OverviewPub/Sub