@ggpwnkthx/duckdb

Type-safe DuckDB FFI binding library for Deno.

Important: This library is tightly coupled to specific DuckDB and Deno versions. It is not guaranteed to work with other versions.

The library uses direct memory access for high-performance result decoding and makes assumptions about DuckDB's internal memory layout. These assumptions are only guaranteed for the versions above. Do not upgrade DuckDB or @ggpwnkthx/libduckdb without thorough testing.

import * as functional from "jsr:@ggpwnkthx/duckdb/functional";
import { Database } from "jsr:@ggpwnkthx/duckdb/objective";

Or via deno.json import map:

{
  "imports": {
    "@ggpwnkthx/duckdb/functional": "jsr:@ggpwnkthx/duckdb@1.2.0/functional",
    "@ggpwnkthx/duckdb/objective": "jsr:@ggpwnkthx/duckdb@1.2.0/objective"
  }
}

Pure functions; handles are managed manually.

import * as functional from "jsr:@ggpwnkthx/duckdb/functional";

const db = await functional.open();
const conn = await functional.connectToDatabase(db);
try {
  const rows = functional.queryObjects(conn, "SELECT 42 AS answer");
  console.log(rows);
} finally {
  functional.closeConnection(conn);
  functional.closeDatabase(db);
}

Classes with Symbol.dispose for automatic cleanup.

import { Database } from "jsr:@ggpwnkthx/duckdb/objective";

using db = await Database.open();
using conn = await db.connect();
const rows = conn.queryObjects("SELECT 42 AS answer");
console.log(rows);

DuckDB values surface as the following JavaScript types:

DECIMAL/ENUM/UUID/BIT and other complex types are returned as exact text via DuckDB's legacy value conversion helpers. This avoids silent precision loss while keeping the public API simple and serializable.

All errors extend DuckDBError (which extends Error) and carry a code:

Typical dev/test usage requires --allow-ffi, --allow-read, --allow-env. If the native library must be auto-downloaded, also --allow-net and --allow-write.

• GitHub repo
• JSR package
• Wiki — full API reference, configuration catalog, value-decoding details, examples index
• Examples — getting-started, configuration, analytics, data-types, cloud
• Benchmarks — run with deno task bench
• CHANGELOG.md
• LICENSE (MIT)