@ducklings/browser

Minimal DuckDB WASM for browsers. Async worker-based API with full TypeScript support.

Installation

npm install @ducklings/browser
Copy

Quick Start

import { init, DuckDB } from '@ducklings/browser';

// Initialize the WASM module (runs in Web Worker)
await init();

// Create database and connection
const db = new DuckDB();
const conn = await db.connect();

// Query returns array of JS objects
const rows = await conn.query<{answer: number}>('SELECT 42 as answer');
console.log(rows); // [{ answer: 42 }]

// Clean up
await conn.close();
await db.close();
Copy

Features

• Async API - queries run in Web Worker, UI stays responsive
• ~7.1 MiB gzipped WASM
• Built-in Parquet and httpfs extensions
• Arrow Table support via Flechette (query + insert)
• Prepared statements with type-safe parameter binding
• Streaming results for large datasets
• Transaction support
• File registration (URL, buffer, text)

Extension Availability

The published browser package bundles Parquet and httpfs. It does not bundle DuckDB's json, Avro, or Iceberg extensions, so the WASM stays under Cloudflare Pages' 25 MiB per-file limit. For Avro and Iceberg, use @ducklings/workers-iceberg on Cloudflare Workers.

JSON functions such as json_extract(...), the ::JSON type alias, and file readers like read_json() are therefore not available in the standard @ducklings/browser package. Use a custom build if you need DuckDB's json extension.

API

Initialization

import { init, DuckDB, version } from '@ducklings/browser';

// Auto-locate WASM and worker files
await init();

// Custom URLs (optional)
await init({
  wasmUrl: '/path/to/duckdb.wasm',
  workerUrl: '/path/to/worker.js'
});

// Create database
const db = new DuckDB();

// Get DuckDB version
const v = await version(); // "v1.4.3"
Copy

CDN Usage

Load directly from jsDelivr or unpkg - cross-origin workers are handled automatically:

<script type="module">
  import { init, DuckDB } from 'https://cdn.jsdelivr.net/npm/@ducklings/[email protected]/+esm';

  await init();

  const db = new DuckDB();
  const conn = await db.connect();
  const result = await conn.query('SELECT 42 as answer');
  console.log(result); // [{ answer: 42 }]

  await conn.close();
  await db.close();
</script>
Copy

Bundler Usage (Vite / Webpack)

When using a bundler, import asset URLs explicitly instead of relying on auto-resolution:

Vite:

import { init, DuckDB } from '@ducklings/browser';
import wasmUrl from '@ducklings/browser/wasm/duckdb.wasm?url';
import wasmJsUrl from '@ducklings/browser/wasm/duckdb.js?url';
import workerUrl from '@ducklings/browser/worker?url';

await init({ wasmUrl, wasmJsUrl, workerUrl });
Copy

Webpack:

import { init, DuckDB } from '@ducklings/browser';

const wasmUrl = new URL('@ducklings/browser/wasm/duckdb.wasm', import.meta.url).href;
const wasmJsUrl = new URL('@ducklings/browser/wasm/duckdb.js', import.meta.url).href;
const workerUrl = new URL('@ducklings/browser/worker', import.meta.url).href;

await init({ wasmUrl, wasmJsUrl, workerUrl });
Copy

Query Methods

const conn = await db.connect();

// Returns array of objects
const rows = await conn.query<{id: number, name: string}>('SELECT * FROM users');

// Returns Arrow Table (Flechette)
const table = await conn.queryArrow('SELECT * FROM users');

// Execute without returning results
await conn.execute('INSERT INTO users VALUES (1, "Alice")');

// Insert Arrow IPC data into a table
const ipc = tableToIPC(arrowTable, { format: 'stream' });
await conn.insertArrowFromIPCStream('my_table', ipc);
Copy

Prepared Statements

const stmt = await conn.prepare('SELECT * FROM users WHERE id = ? AND active = ?');
stmt.bindInt32(1, 42);      // Bind methods are sync
stmt.bindBoolean(2, true);
const results = await stmt.run();  // Execution is async
await stmt.close();
Copy

Streaming Results

const stream = await conn.queryStreaming('SELECT * FROM large_table');

for await (const chunk of stream) {
  console.log(`Processing ${chunk.rowCount} rows`);
  for (const row of chunk.toArray()) {
    processRow(row);
  }
}
// Stream auto-closes after iteration
Copy

File Registration

// Register remote file
await db.registerFileURL('data.parquet', 'https://example.com/data.parquet');

// Register in-memory data
const csvData = new TextEncoder().encode('id,name\n1,Alice');
await db.registerFileBuffer('data.csv', csvData);

// Query registered files
const rows = await conn.query("SELECT * FROM 'data.parquet'");
Copy

Remote Files (httpfs)

// Query remote Parquet file directly
const rows = await conn.query(`
  SELECT * FROM 'https://example.com/data.parquet'
  LIMIT 10
`);
Copy

Arrow Support

import { tableFromArrays, tableFromIPC, tableToIPC, utf8 } from '@ducklings/browser';

// Query as Arrow Table
const table = await conn.queryArrow('SELECT * FROM users');

// Build Arrow tables
const custom = tableFromArrays({
  id: [1, 2, 3],
  name: ['Alice', 'Bob', 'Charlie']
});

// Serialize to/from Arrow IPC
const bytes = tableToIPC(table, { format: 'stream' });
const restored = tableFromIPC(bytes);

// Insert Arrow IPC data directly into a table
const data = tableFromArrays(
  { id: [1, 2], label: ['x', 'y'] },
  { types: { label: utf8() } }  // Use plain utf8 (see note below)
);
const ipc = tableToIPC(data, { format: 'stream' });
await conn.insertArrowFromIPCStream('my_table', ipc);
Copy

Dictionary encoding: Flechette's tableFromArrays() defaults to dictionary(utf8()) for string columns. The Arrow IPC decoder used internally does not support dictionary-encoded streams. When building tables for insertArrowFromIPCStream(), explicitly set string columns to utf8():

import { utf8 } from '@ducklings/browser';
tableFromArrays({ col: ['a', 'b'] }, { types: { col: utf8() } });
Copy

Cloudflare Workers

For Cloudflare Workers, use the @ducklings/workers package instead, which uses Asyncify for proper httpfs support in the Workers runtime.

Limitations

• No dynamic extension loading: Only statically compiled extensions (Parquet, httpfs) are available in the default build. INSTALL/LOAD commands for other extensions will not work.

License

MIT