kalam_link

Official Dart and Flutter client for KalamDB: SQL over HTTP, live rows over WebSocket, and JWT auth.

For a local-first Flutter app (offline cache, optimistic writes), use kalam_sync instead.

→ Docs · Setup · Kalam Sync · GitHub

Install

flutter pub add kalam_link

Point the client at a running KalamDB. Server install and first-user setup are in the server quick start and kalam init.

Get started

import 'package:flutter/widgets.dart';
import 'package:kalam_link/kalam_link.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await KalamClient.init();
  runApp(const MyApp());
}

Connect after the first frame — not before runApp():

final client = await KalamClient.connect(
  url: 'http://localhost:2900',
  authProvider: () async => Auth.basic('root', 'kalamdb123'),
);

final result = await client.query(
  r'SELECT id, title FROM app.tasks WHERE done = $1',
  params: [false],
);

for (final row in result.rows) {
  print('${row['id']?.asInt()} ${row['title']?.asString()}');
}

final tasks = client.liveTable<Map<String, KalamCellValue>>('app.tasks');
await for (final rows in tasks) {
  print('rows=${rows.length}');
  break;
}

await client.dispose();

Live SQL must stay SELECT ... FROM ... WHERE .... Prefer live() / liveTable() for UI lists; use liveEvents() when you need raw insert/update/delete events.

Auth

authProvider: () async => Auth.jwt(await tokens.freshAccessToken()),

Auth.basic(user, password) exchanges credentials for a JWT on connect. Call refreshAuth() when the token rotates. See Authentication.

Local-first Flutter

import 'package:kalam_sync/kalam_sync.dart';

final kalam = await Kalam.open(
  url: 'http://localhost:2900',
  subject: signedInUser.id,
  authProvider: () async => Auth.jwt(await tokens.freshAccessToken()),
);

runApp(KalamScope(kalam: kalam, child: const App()));

Docs: Kalam Sync.

Examples

Protocol demos (need a running server; defaults root / kalamdb123):

dart run example/simple-events/main.dart
dart run example/chat-app/main.dart

New Flutter apps: kalam init --languages dart. See example/README.md.

License

Apache-2.0. See LICENSE.txt.