Skip to main content

DuckDB WebSocket SDK

High-performance TypeScript SDK for connecting to DuckDB server via WebSocket. Designed for low-latency, high-throughput query execution with automatic reconnection and connection pooling support.

Key Features

Auto-Connect

Automatically connects on first query - no manual connect() needed

Auto-Ping

Keeps connection alive with automatic health checks every 30 seconds

WebSocket Connection

Persistent connection with 5-15ms latency (vs 50-100ms for HTTP)

API Key Authentication

Secure authentication using DUCKLING_API_KEY

Auto-Reconnection

Automatic reconnection with exponential backoff on connection failure

Connection Pooling

Built-in support for connection pools and parallel queries

Type-Safe

Full TypeScript support with type inference for query results

High Throughput

10,000+ queries/second capability with connection pooling

Performance Benefits

Latency Comparison

MethodAverage LatencyUse Case
HTTP API50-100msStandard queries
WebSocket SDK5-15msReal-time dashboards

Throughput Metrics

  • Sequential: ~20-50 queries/second
  • Parallel (single connection): ~500-1,000 queries/second
  • Connection Pool (5 connections): ~2,000-5,000 queries/second
  • Maximum Capacity: 10,000+ queries/second

Quick Start

import { DucklingClient } from '@chittihq/duckling';

// Initialize client - auto-connect and auto-ping enabled by default
const client = new DucklingClient({
  url: 'ws://localhost:3001/ws',
  apiKey: process.env.DUCKLING_API_KEY,
  databaseName: 'default'  // Optional - defaults to 'default'
});

// Just query - client auto-connects on first query!
const users = await client.query('SELECT * FROM User LIMIT 10');

// Auto-ping keeps connection alive
// Close when done
client.close();

Multi-Database Support

Each WebSocket connection is bound to one database. To query multiple databases, create multiple client instances:
// Connect to different databases
const lmsClient = new DucklingClient({
  url: 'ws://localhost:3001/ws',
  apiKey: process.env.DUCKLING_API_KEY,
  databaseName: 'lms'
});

const chittiClient = new DucklingClient({
  url: 'ws://localhost:3001/ws',
  apiKey: process.env.DUCKLING_API_KEY,
  databaseName: 'chitti_common'
});

// Each client queries its own database
const lmsUsers = await lmsClient.query('SELECT * FROM User');
const chittiActions = await chittiClient.query('SELECT * FROM Action');

// Clean up
lmsClient.close();
chittiClient.close();

Architecture

Dashboard → SDK → WebSocket → DuckDB Server

     [Connection Pool]
     [Auto-Reconnect]
     [Query Queuing]

Use Cases

Real-Time Dashboards

// Update dashboard every second with fresh data
setInterval(async () => {
  const stats = await client.query('SELECT * FROM dashboard_stats');
  updateUI(stats);
}, 1000);

Batch Processing

// Process 1000 queries efficiently
const queries = generateQueries(1000);
const batchSize = 50;

for (let i = 0; i < queries.length; i += batchSize) {
  const batch = queries.slice(i, i + batchSize);
  const results = await client.queryBatch(batch);
  processBatch(results);
}

Microservices Integration

// API endpoint handler
app.get('/api/users/:id', async (req, res) => {
  const user = await client.query(
    'SELECT * FROM User WHERE id = ?',
    [req.params.id]
  );
  res.json(user[0]);
});

Next Steps

Installation

Install the SDK in your project

Client API

Explore DucklingClient methods

TypeScript Types

Learn about type definitions

Examples

See real-world usage examples

Build docs developers (and LLMs) love