Installation
Install the DuckDB WebSocket SDK in your TypeScript or JavaScript project.
Package Installation
npm install @chittihq/duckling
Requirements
- Node.js: 18.0.0 or higher
- TypeScript: 5.0.0 or higher (optional, for type support)
- DuckDB Server: WebSocket-enabled DuckDB server instance
- API Key: Valid
DUCKLING_API_KEY for authentication
Environment Setup
Create a .env file in your project root:
DUCKLING_API_KEY=your-api-key-here
DUCKLING_WS_URL=ws://localhost:3001/ws # Optional, defaults to this
Basic Configuration
import { DucklingClient } from '@chittihq/duckling';
const client = new DucklingClient({
url: process.env.DUCKLING_WS_URL || 'ws://localhost:3001/ws',
apiKey: process.env.DUCKLING_API_KEY!,
databaseName: 'default' // Optional - defaults to 'default'
});
Configuration Options
All configuration options with their defaults:
WebSocket server URL (e.g., ws://localhost:3001/ws)
API key for authentication
Database name to connect to
Automatically connect on first query (no manual connect() needed)
Automatically ping server to keep connection alive
Ping interval in milliseconds (default: 30 seconds)
Automatically reconnect on connection failure
Maximum number of reconnection attempts
Initial reconnect delay in milliseconds (uses exponential backoff)
Connection timeout in milliseconds
Enable logging of queries and results
logLevel
'error' | 'warn' | 'info' | 'debug'
default:"'info'"
Log level for debugging
Advanced Configuration
Custom Connection Settings
const client = new DucklingClient({
url: 'wss://production.example.com/ws',
apiKey: process.env.DUCKLING_API_KEY!,
databaseName: 'production',
// Connection behavior
autoConnect: true,
autoReconnect: true,
maxReconnectAttempts: 10,
reconnectDelay: 2000,
connectionTimeout: 10000,
// Keep-alive settings
autoPing: true,
pingInterval: 60000, // Ping every 60 seconds
// Debugging
enableLogging: true,
logLevel: 'debug'
});
Production Configuration
const client = new DucklingClient({
url: process.env.DUCKLING_WS_URL!,
apiKey: process.env.DUCKLING_API_KEY!,
databaseName: process.env.DATABASE_NAME || 'default',
// Aggressive reconnection for production
autoReconnect: true,
maxReconnectAttempts: 10,
reconnectDelay: 1000,
// Long-lived connections
autoPing: true,
pingInterval: 30000,
// Error logging only
enableLogging: true,
logLevel: 'error'
});
Development Configuration
const client = new DucklingClient({
url: 'ws://localhost:3001/ws',
apiKey: process.env.DUCKLING_API_KEY!,
databaseName: 'development',
// Verbose logging for debugging
enableLogging: true,
logLevel: 'debug',
// Quick ping for testing
pingInterval: 5000
});
TypeScript Configuration
Add type definitions to your tsconfig.json:
{
"compilerOptions": {
"target": "ES2020",
"module": "ESNext",
"moduleResolution": "node",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true,
"resolveJsonModule": true
}
}
Verify Installation
Test your installation with a simple query:
import { DucklingClient } from '@chittihq/duckling';
const client = new DucklingClient({
url: 'ws://localhost:3001/ws',
apiKey: process.env.DUCKLING_API_KEY!,
enableLogging: true
});
async function test() {
try {
// Auto-connects on first query
const result = await client.query('SELECT 1 as test');
console.log('✓ Connection successful:', result);
} catch (error) {
console.error('✗ Connection failed:', error);
} finally {
client.close();
}
}
test();
DUCKLING_API_KEY=your-key npx tsx test.ts
Troubleshooting
Increase connectionTimeout if connecting to a remote server:const client = new DucklingClient({
url: 'wss://remote.example.com/ws',
apiKey: process.env.DUCKLING_API_KEY!,
connectionTimeout: 10000 // 10 seconds
});
Verify your API key is correct:Make sure it matches the key configured on the server. WebSocket Connection Refused
Check that the DuckDB server is running:curl http://localhost:3001/health
ws:// (not http://).
Reinstall dependencies:rm -rf node_modules package-lock.json
npm install
Next Steps
Client API
Learn about DucklingClient methods
TypeScript Types
Explore type definitions
Examples
See usage examples