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)
• Subscribe to any SELECT query live over WebSocket (subscribe)
• Consume reconciled materialized live rows (liveQueryRowsWithSql, liveTableRows)
• Authenticate with JWT, Basic, 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:

dependencies:
  kalam_link: ^0.4.1-beta.2

Then run:

flutter pub get
# or
dart pub get

Initialization

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

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

Quick start

import 'package:kalam_link/kalam_link.dart';
 
Future<void> run() async {
  final client = await KalamClient.connect(
    url: 'https://db.example.com',
    authProvider: () async {
      final token = await myApp.getOrRefreshJwt();
      return Auth.jwt(token);
    },
    logLevel: Level.debug,
    logListener: (entry) => debugPrint(entry.toString()),
  );
 
  final result = await client.query('SELECT id, email FROM users LIMIT 10');
  for (final row in result.rows) {
    print('${row['id']?.asString()} ${row['email']?.asString()}');
  }
 
  // Live subscription
  final stream = client.subscribe("SELECT * FROM support.messages WHERE room = 'main'");
  await for (final event in stream) {
    switch (event) {
      case InsertEvent(:final row):
        print('New message: $row');
      default:
        break;
    }
  }
 
  // Materialized live rows
  final rowsStream = client.liveTableRows<Map<String, KalamCellValue>>('app.tasks');
  await for (final rows in rowsStream) {
    print('rows=${rows.length}');
    break;
  }
 
  await client.dispose();
}

For subscribe() 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 subscriptions by cancelling your StreamSubscription.
• Use subscribe() for realtime SQL change streams.
• Prefer liveQueryRowsWithSql() or liveTableRows() 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.

import 'package:logger/logger.dart' show Level;
 
final client = await KalamClient.connect(
  url: 'http://localhost:8080',
  authProvider: () async => Auth.jwt(await getJwt()),
  logLevel: Level.debug,
  logListener: (entry) {
    debugPrint('[${entry.tag}] ${entry.message}');
  },
);

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