Dart / Flutter SDK

kalam_link is the official KalamDB client for Dart and Flutter. It wraps the compiled Rust core via Flutter Rust Bridge v2, giving you native-speed queries and live subscriptions with a simple Dart API.

Status: This SDK is in beta and may still change between releases.

What you can do

kalam_link currently focuses on the core app-client workflows:

• Execute SQL over HTTP (query)
• Open any SELECT query live over WebSocket (liveEvents)
• Consume reconciled materialized live rows (live, liveTable)
• Authenticate with JWT, user/password bootstrap, or anonymous access (authProvider, login, refreshToken, refreshAuth)
• Observe connection lifecycle (connectionHandlers)
• Inspect active subscriptions (getSubscriptions)
• Control the shared WebSocket explicitly (isConnected, disconnectWebSocket, reconnectWebSocket)

The current Dart SDK does not expose Topic consumer / ACK worker APIs.

Installation

Add to your pubspec.yaml:

1dependencies:2kalam_link: ^0.5.0-beta.1

Then run:

1flutter pub get2# or3dart pub get

Initialization

Call KalamClient.init() once at app startup before creating any clients:

1void main() async {2  WidgetsFlutterBinding.ensureInitialized();3  await KalamClient.init();4  runApp(const MyApp());5}

Quick start

1import 'package:kalam_link/kalam_link.dart';2 3Future<void> run() async {4  final client = await KalamClient.connect(5    url: 'https://db.example.com',6    authProvider: () async {7      final token = await myApp.getOrRefreshJwt();8      return Auth.jwt(token);9    },10    logLevel: Level.debug,11    logListener: (entry) => debugPrint(entry.toString()),12  );13 14  final result = await client.query('SELECT id, email FROM users LIMIT 10');15  for (final row in result.rows) {16    print('${row['id']?.asString()} ${row['email']?.asString()}');17  }18 19  // Low-level live events20  final stream = client.liveEvents("SELECT * FROM support.messages WHERE room = 'main'");21  await for (final event in stream) {22    switch (event) {23      case InsertEvent(:final row):24        print('New message: $row');25      default:26        break;27    }28  }29 30  // Materialized live rows31  final rowsStream = client.liveTable<Map<String, KalamCellValue>>('app.tasks');32  await for (final rows in rowsStream) {33    print('rows=${rows.length}');34    break;35  }36 37  await client.dispose();38}

For liveEvents() and materialized live-query APIs, keep the SQL strict: SELECT ... FROM ... WHERE .... Do not include ORDER BY or LIMIT inside the live SQL.

Recommended reading order

1. Setup & Quick Start
2. Authentication
3. Auth-Aware Client
4. Querying & DML
5. Realtime Subscriptions
6. Client Lifecycle
7. Types & Models
8. Server Setup & Diagnostics Boundary

Supported platforms

This package is a Flutter FFI plugin (via Flutter Rust Bridge) and is configured for:

• Android, iOS
• macOS, Windows, Linux

Notes

• Call KalamClient.init() exactly once at startup.
• Prefer authProvider for expiring tokens.
• Cancel live streams by cancelling your StreamSubscription.
• Use liveEvents() for realtime SQL change streams.
• Prefer live() or liveTable() when your UI wants the latest reconciled row list.
• Use getSubscriptions() and SeqId if you need resume-aware client bookkeeping.
• Native Dart subscriptions use MessagePack by default on the shared Rust transport.

Connection options

SDK logging

The Dart SDK uses Level from package:logger/logger.dart for log severity.

1import 'package:logger/logger.dart' show Level;2 3final client = await KalamClient.connect(4  url: 'http://localhost:2900',5  authProvider: () async => Auth.jwt(await getJwt()),6  logLevel: Level.debug,7  logListener: (entry) {8    debugPrint('[${entry.tag}] ${entry.message}');9  },10);

When logListener is not set, the SDK falls back to print(...), which is visible in Flutter/Android consoles.