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() neededAuto-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
| Method | Average Latency | Use Case |
|---|---|---|
| HTTP API | 50-100ms | Standard queries |
| WebSocket SDK | 5-15ms | Real-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
Multi-Database Support
Each WebSocket connection is bound to one database. To query multiple databases, create multiple client instances:Architecture
Use Cases
Real-Time Dashboards
Batch Processing
Microservices Integration
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