Transport & Endpoints
The Dart SDK is a high-level wrapper over the same public endpoints described in the API reference.
SQL execution (HTTP)
query(...) executes SQL over the HTTP SQL endpoint.
- See: HTTP API Reference
- See: SQL Reference
The SDK passes params as JSON (for $1, $2, … placeholders).
Related auth endpoints used by the SDK:
login(...)→POST /v1/api/auth/loginrefreshToken(...)→POST /v1/api/auth/refresh
FILE download helpers use the shared KalamDB file endpoint:
| Method | Endpoint | Dart helpers |
|---|---|---|
GET | /v1/files/{namespace}/{table}/{sub}/{stored_name} | KalamFileRef.getDownloadUrl(...), KalamCellValue.asFileUrl(...) |
The last path segment is the stored filename generated by the shared
link-common FileRef model. It is not the raw file id by itself.
For user tables, these helpers generate owner-scoped URLs. A regular user can
download only their own files; service tokens can write through authorized
EXECUTE AS USER flows, but direct cross-user FILE byte downloads require a
dba or system token with an authorized user_id query parameter.
Live subscriptions (WebSocket)
subscribe(...) uses the WebSocket realtime endpoint.
- See: WebSocket Protocol
- See: Architecture: Live Query
On native Dart and Flutter targets, the shared subscription connection defaults to MessagePack serialization. Browser/WASM behavior is separate and may differ by release.
Debugging compression
By default, the server may send gzip-compressed frames. For local debugging, disable compression:
final client = await KalamClient.connect( url: 'http://localhost:2900', authProvider: () async => Auth.jwt(await getJwt()), disableCompression: true,);This appends ?compress=false to the WS URL so you can more easily inspect frames.
Do not enable in production. Compression reduces bandwidth and improves performance.
Timeouts and retries
timeoutcontrols HTTP request timeout for queries.maxRetriescontrols retry count for idempotent queries (typicallySELECT).
final client = await KalamClient.connect( url: 'http://localhost:2900', authProvider: () async => Auth.jwt(await getJwt()), timeout: const Duration(seconds: 10), maxRetries: 2,);