SDK Overview

[dependencies]
kimberlite = "1.0"

pip install kimberlite

npm install @kimberlitedb/client
# or
yarn add @kimberlitedb/client

go get github.com/kimberlitedb/kimberlite-go

use kimberlite::{Client, TenantId, StreamId};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connect
    let client = Client::connect("localhost:3000").await?;

    // Append event
    let position = client.append(
        TenantId::new(1),
        StreamId::new(1, 100),
        b"event data"
    ).await?;

    // Read events
    let events = client.read_stream(
        TenantId::new(1),
        StreamId::new(1, 100)
    ).await?;

    Ok(())
}

from kimberlite import Client, TenantId, StreamId

# Connect
client = Client("localhost:3000")

# Append event
position = client.append(
    TenantId(1),
    StreamId(1, 100),
    b"event data"
)

# Read events
events = client.read_stream(TenantId(1), StreamId(1, 100))

import { Client, TenantId, StreamId } from '@kimberlitedb/client';

// Connect
const client = await Client.connect('localhost:3000');

// Append event
const position = await client.append(
  new TenantId(1),
  new StreamId(1, 100),
  Buffer.from('event data')
);

// Read events
const events = await client.readStream(
  new TenantId(1),
  new StreamId(1, 100)
);

// Create client
let client = Client::connect("localhost:3000").await?;

// With authentication
let client = Client::connect_with_auth(
    "localhost:3000",
    TenantId::new(1),
    "api_key"
).await?;

// With TLS
let client = Client::connect_with_tls(
    "localhost:3000",
    tls_config
).await?;

let tenant = TenantId::new(1);

let stream = StreamId::new(tenant_id, stream_number);

let position = Position::new(1000);
let events = client.read_from_position(position).await?;

// Single event
let position = client.append(tenant, stream, event_data).await?;

// Batch append (more efficient)
let positions = client.append_batch(tenant, stream, events).await?;

// Read entire stream
let events = client.read_stream(tenant, stream).await?;

// Read from position
let events = client.read_from_position(position).await?;

// Read with limit
let events = client.read_stream_with_limit(tenant, stream, 100).await?;

// Subscribe to new events
let mut subscription = client.subscribe(tenant, stream).await?;

while let Some(event) = subscription.next().await {
    println!("New event: {:?}", event);
}

// Create client pool
let pool = ClientPool::builder()
    .max_connections(10)
    .connect("localhost:3000")
    .await?;

// Get client from pool
let client = pool.get().await?;
client.append(tenant, stream, data).await?;

let client = Client::builder()
    .reconnect_policy(ReconnectPolicy::Exponential {
        min_delay: Duration::from_secs(1),
        max_delay: Duration::from_secs(60),
        max_attempts: 10,
    })
    .connect("localhost:3000")
    .await?;

let client = Client::builder()
    .timeout(Duration::from_secs(30))
    .connect("localhost:3000")
    .await?;

use kimberlite::{Client, Error};

match client.append(tenant, stream, data).await {
    Ok(position) => println!("Appended at {}", position),
    Err(Error::Unauthorized) => println!("Authentication failed"),
    Err(Error::NetworkError(e)) => println!("Network error: {}", e),
    Err(e) => println!("Other error: {}", e),
}

from kimberlite import Client, KimberliteError, UnauthorizedError

try:
    position = client.append(tenant, stream, data)
except UnauthorizedError:
    print("Authentication failed")
except KimberliteError as e:
    print(f"Error: {e}")

import { Client, KimberliteError, UnauthorizedError } from '@kimberlitedb/client';

try {
  const position = await client.append(tenant, stream, data);
} catch (e) {
  if (e instanceof UnauthorizedError) {
    console.log('Authentication failed');
  } else if (e instanceof KimberliteError) {
    console.log(`Error: ${e.message}`);
  }
}

let client = Client::connect_with_auth(
    "localhost:3000",
    TenantId::new(1),
    "your-api-key"
).await?;

use kimberlite::tls::{TlsConfig, ClientCert};

let tls_config = TlsConfig::builder()
    .client_cert(ClientCert::from_pem(cert_pem, key_pem)?)
    .ca_cert(ca_pem)
    .build()?;

let client = Client::connect_with_tls("localhost:3000", tls_config).await?;

let client = Client::builder()
    .timeout(Duration::from_secs(30))
    .max_retries(3)
    .compression(true)
    .keepalive(Duration::from_secs(60))
    .connect("localhost:3000")
    .await?;

client = Client(
    "localhost:3000",
    timeout=30,
    max_retries=3,
    compression=True,
    keepalive=60
)

const client = await Client.connect('localhost:3000', {
  timeout: 30000,
  maxRetries: 3,
  compression: true,
  keepalive: 60000
});

// ❌ Slow: Individual appends
for event in events {
    client.append(tenant, stream, event).await?;
}

// ✅ Fast: Batch append
client.append_batch(tenant, stream, events).await?;

let client = Client::builder()
    .compression(true)
    .connect("localhost:3000")
    .await?;

use kimberlite::testing::MockClient;

#[tokio::test]
async fn test_append() {
    let client = MockClient::new();
    client.expect_append()
        .with(tenant, stream, data)
        .returning(|_, _, _| Ok(Position::new(1)));

    let position = client.append(tenant, stream, data).await?;
    assert_eq!(position, Position::new(1));
}

from kimberlite.testing import MockClient

def test_append():
    client = MockClient()
    client.expect_append(tenant, stream, data).returns(Position(1))

    position = client.append(tenant, stream, data)
    assert position == Position(1)

// Before: PostgreSQL
let pool = PgPool::connect("postgresql://...").await?;
let row = sqlx::query!("SELECT * FROM users WHERE id = $1", id)
    .fetch_one(&pool)
    .await?;

// After: Kimberlite (SQL)
let client = Client::connect("localhost:3000").await?;
let row = client.query("SELECT * FROM users WHERE id = $1", &[id]).await?;