Kalam Sync

kalam_sync keeps a local Drift cache so Flutter UI works offline, then syncs live SQL through kalam_link.

Need a server first? kalam init or the server quick start.

Fastest path

1kalam init --yes --languages dart --template simple-live2kalam schema gen --languages dart3kalam dev

That writes a Flutter starter, schema.sql, and KalamTables.*. Or add the package yourself:

1dependencies:2kalam_sync: ^0.6.0-rc.0

1flutter pub add kalam_sync

Open one account-scoped cache

1import 'package:flutter/material.dart';2import 'package:kalam_sync/kalam_sync.dart';3 4Future<void> main() async {5  WidgetsFlutterBinding.ensureInitialized();6 7  final kalam = await Kalam.open(8    url: 'http://localhost:2900',9    subject: 'dev-user',10    namespace: 'app',11    authProvider: () async => Auth.basic('root', 'kalamdb123'),12  );13 14  runApp(KalamScope(kalam: kalam, child: const App()));15}

subject is required. The server URL, namespace, and authenticated subject form the local database identity, so one user’s cached rows and queued actions cannot be opened or flushed as another user.

Production apps should pass the signed-in user id and return Auth.jwt(...) from authProvider.

Kalam.open() initializes the Rust runtime and opens SQLite immediately. The WebSocket stays lazy until the first consumer or queued action needs it. KalamScope pauses and resumes sync with the Flutter app lifecycle.

Bind a table and subscribe

kalam schema gen --languages dart writes row classes and KalamTables.* specs from schema.sql. Bind that spec — do not invent a second model:

1final todos = kalam.table(KalamTables.todos);2 3late final KalamSyncSubscription todoSync;4 5Future<void> startTodos() async {6  todoSync = await kalam.subscribe(7    todos.consumer(sql: 'SELECT * FROM app.todos', batchSize: 250),8  );9}10 11Future<void> addTodo(String title) {12  return todos.insert(13    Todos(14      id: Kalam.id(),15      title: title,16      completed: false,17    ),18    actionId: Kalam.id(),19  );20}

insert, update, and delete change the local row and enqueue one generic Kalam DML action in the same SQLite transaction. todos.watch() is always local and keeps working offline.

Live SQL must stay SELECT ... FROM ... WHERE .... Do not put ORDER BY or LIMIT in the consumer SQL.

Watch rows in the UI

1StreamBuilder<List<KalamSyncedRow<Todos>>>(2  stream: todos.watchWithSyncState(),3  builder: (context, snapshot) {4    final rows = snapshot.data ?? const <KalamSyncedRow<Todos>>[];5    return ListView(6      children: [7        for (final row in rows)8          ListTile(9            title: Text(row.value.title),10            trailing: Icon(11              row.isSynced ? Icons.cloud_done : Icons.cloud_upload,12            ),13          ),14      ],15    );16  },17)

watch() returns decoded rows only. Use watchWithSyncState() when the UI needs pending, retry, failure, or awaiting-server-echo state beside each row.

That’s enough for a first Flutter list. The rest of this page is optional.

Subscribe inside a widget

Start only the query the screen needs, and cancel it when the widget unloads:

1import 'dart:async';2 3class TodoListState extends State<TodoList> {4  late final KalamTableBinding<Todos> todos;5  KalamSyncSubscription? sync;6 7  @override8  void initState() {9    super.initState();10    final kalam = KalamScope.read(context);11    todos = kalam.table(KalamTables.todos);12    kalam13        .subscribe(todos.consumer(sql: 'SELECT * FROM app.todos'))14        .then((value) {15          if (mounted) {16            sync = value;17          } else {18            unawaited(value.cancel());19          }20        });21  }22 23  @override24  void dispose() {25    sync?.cancel();26    super.dispose();27  }28}

Use KalamScope.read(context) in initState. KalamScope.of(context) rebuilds when the session changes.

consumer() accepts the same params list as query():

1messages.consumer(2  sql: r'SELECT * FROM app.messages WHERE conversation_id = $1',3  params: [conversationId],4)

Later: catch-up, table modes, durability

Catch up in a headless isolate

The same live query can drain a bounded backlog, then disconnect:

1final result = await Kalam.catchUp(2  url: serverUrl,3  subject: userId,4  namespace: 'app',5  authProvider: () async => Auth.jwt(await tokens.freshAccessToken()),6  consumers: [todos.consumer(sql: 'SELECT * FROM app.todos')],7  rowLimit: 100,8  timeout: const Duration(seconds: 30),9);

Catch-up resumes from: the SQLite-committed checkpoint and uses batchSize as the row limit.

Table modes

Stream tables generate as replicaOnly. User and shared tables generate as bidirectional. Override with spec.copyWith(mode: ...) when the backend must stay authoritative.

Custom actions, generated queues, and named steps are in Offline Actions.

What stays durable

• Local mirror row + outbox enqueue are one Drift transaction.
• Applied server row + sequence checkpoint are one Drift transaction.
• Server deliveries are acknowledged only after that transaction commits.
• Duplicate or older events are ignored.
• Actions, retry metadata, optimistic rows, and checkpoints survive process restart.
• pause() / resume() cancel and reopen subscriptions from the SQLite-committed checkpoint.

kalam_sync uses kalam_link.liveEventsWithAck. Existing liveEvents() callers keep automatic progress; sync subscriptions resume from the committed cursor after reconnect or process restart.

Next

• Offline Actions
• kalam_link setup
• CLI Dart starter
• pub.dev: kalam_sync