Realtime

Subscribe to live database changes over WebSocket. Your app receives events instantly when records are created, updated, or deleted.

How it works

Koolbase Realtime uses a persistent WebSocket connection to the server. When any record in a subscribed collection is mutated, the server broadcasts the event to all connected clients subscribed to that collection.

Subscriptions are reference-counted — multiple subscribers on the same collection share one connection. The connection is automatically managed by the SDK.

Subscribe to a collection

lib/realtime.dartDart

// Subscribe to all events on a collection
final subscription = Koolbase.realtime.on(
  collection: 'posts',
  onCreated: (record) {
    print('New post: ${record.data['title']}');
    setState(() => posts.insert(0, record));
  },
  onUpdated: (record) {
    print('Post updated: ${record.id}');
    setState(() {
      final index = posts.indexWhere((p) => p.id == record.id);
      if (index != -1) posts[index] = record;
    });
  },
  onDeleted: (recordId) {
    print('Post deleted: $recordId');
    setState(() => posts.removeWhere((p) => p.id == recordId));
  },
);

Unsubscribe

Always cancel subscriptions when the widget is disposed to prevent memory leaks:

lib/realtime.dartDart

class PostsScreen extends StatefulWidget {
  @override
  State<PostsScreen> createState() => _PostsScreenState();
}

class _PostsScreenState extends State<PostsScreen> {
  KoolbaseSubscription? _subscription;

  @override
  void initState() {
    super.initState();
    _subscription = Koolbase.realtime.on(
      collection: 'posts',
      onCreated: (record) => setState(() => posts.insert(0, record)),
    );
  }

  @override
  void dispose() {
    _subscription?.cancel();
    super.dispose();
  }
}

Event types

onCreatedKoolbaseRecordA new record was inserted into the collection

onUpdatedKoolbaseRecordAn existing record was updated — full updated record included

onDeletedString (record id)A record was deleted — only the ID is provided

Connection state

lib/realtime.dartDart

// Listen to connection state changes
Koolbase.realtime.connectionState.listen((state) {
  switch (state) {
    case RealtimeConnectionState.connected:
      print('Realtime connected');
    case RealtimeConnectionState.disconnected:
      print('Realtime disconnected — will reconnect');
    case RealtimeConnectionState.reconnecting:
      print('Reconnecting...');
  }
});

Auto-reconnect

The SDK automatically reconnects if the WebSocket connection is lost. Subscriptions are re-registered after reconnection. You don't need to manually re-subscribe.

Authenticated subscriptions

If the collection's read rule is authenticated or owner, you must set the session token before subscribing:

lib/realtime.dartDart

// After login, set the token for realtime
final session = await Koolbase.auth.login(email: email, password: password);
Koolbase.realtime.setToken(session.token);

// Now subscribe to authenticated collections
final sub = Koolbase.realtime.on(collection: 'private-notes', onCreated: ...);

Owner-rule collections

For collections with owner read rule, realtime events are filtered server-side — you will only receive events for records where created_by == your user id.