@duckviz/db

In-browser SQL data engine powered by DuckDB-WASM. Handles file ingestion (CSV, XLSX, JSON, JSONL, XML), query execution, table persistence to IndexedDB, and log parsing — all client-side with zero server dependencies.

Install

npm install @duckviz/db
# peer dependencies
npm install @duckdb/duckdb-wasm apache-arrow react

Quick start

import { DuckvizDBProvider, useDuckDB } from "@duckviz/db";

function App() {
  return (
    <DuckvizDBProvider persistence>
      <DataView />
    </DuckvizDBProvider>
  );
}

function DataView() {
  const { runQuery, loading } = useDuckDB();

  async function fetchData() {
    const rows = await runQuery("SELECT * FROM my_table LIMIT 100");
    console.log(rows);
  }

  if (loading) return <p>Initializing DuckDB...</p>;
  return <button onClick={fetchData}>Query</button>;
}

Configuration

All configuration is via props on <DuckvizDBProvider>:

<DuckvizDBProvider
  persistence // Persist tables to IndexedDB across page refreshes (default: false)
  arrowIngest // Use Arrow IPC for batch ingestion — faster, falls back to JSON (default: true)
  batchSize={5000} // Batch size for the file-ingestion worker (default: 5000)
  logLevel="warn" // Console verbosity: "silent" | "warn" | "debug" (default: "warn")
>
  <YourApp />
</DuckvizDBProvider>

API

Provider & hooks

| Export | Description | | --------------------- | ------------------------------------------------- | | <DuckvizDBProvider> | React context provider — initializes DuckDB-WASM | | useDuckDB() | Hook returning the full DuckDBContextValue | | useDuckDBOrNull() | Same as above but returns null outside provider |

Context value (useDuckDB())

| Method | Description | | ------------------------------- | ------------------------------------------------ | | runQuery(sql) | Execute SQL, returns Record<string, unknown>[] | | ingest({ files, onProgress }) | Ingest files via Web Worker with progress | | ingestJsonRows(rows, table) | Ingest parsed rows as a JSON table | | getTableData(table) | Get all rows from a table | | getTableSchema(table) | Get SchemaColumn[] for a table | | listTables() | List all t_* tables | | tableExists(table) | Check if a table exists | | clearAllTables() | Drop all t_* tables |

Core utilities

import { pathToTableName } from "@duckviz/db";

• pathToTableName(path) — Convert file path to valid DuckDB table name (t_ prefix)

Peer dependencies

| Package | Version | | --------------------- | --------- | | react | >=18 | | @duckdb/duckdb-wasm | ^1.33.0 | | apache-arrow | >=14 |

License

MIT