DuckDB Async NodeJS Wrappers

Common errors

• TypeError: Cannot read properties of undefined (reading 'all') at new Database

  cause Attempting to instantiate `Database` directly with `new Database(...)`.
  fix The `Database` constructor is callback-based. You must use the static asynchronous factory method `await Database.create(...)` instead of `new Database(...)` to correctly initialize the database.

• TypeError: db.each(...).then is not a function

  cause Attempting to use `await` or `.then()` directly on the `each` method, which is callback-based.
  fix The `each` method does not return a Promise. Pass a callback function as an argument: `db.each('SELECT * FROM users', (err, row) => { /* handle row */ });`.

Warnings

• breaking The `duckdb-async` package, along with `duckdb-node`, is explicitly deprecated by the maintainers in favor of the new `@duckdb/node-api` package. Future DuckDB versions (1.5.x onwards, ~Early 2026) will not be supported by `duckdb-async`.
  Fix: Migrate to the `@duckdb/node-api` package for continued support and new features. Review its documentation for API changes and adjust your codebase accordingly.
• gotcha The `each` method on `Connection`, `Database`, and `Statement` classes retains its original callback-based interface and does not return a Promise. This is because promises resolve once, while `each` invokes a callback for every row.
  Fix: Continue to use the callback pattern for `each` or refactor your logic to use `all` to fetch all rows into an array and then iterate over them.

Install

• npm install duckdb-async npm
• yarn add duckdb-async yarn
• pnpm add duckdb-async pnpm

Imports

• Database
  wrong:

  import Database from 'duckdb-async';

  correct:

  import { Database } from 'duckdb-async';

  The `Database` class is a named export. Its constructor is callback-based; use the static `Database.create()` method for an async, promise-based initialization.
• Connection
  wrong:

  const { Connection } = require('duckdb-async'); // Incorrect for modern ESM/TypeScript projects

  correct:

  import { Connection } from 'duckdb-async';

  Provides Promise-based methods for executing SQL queries on an established database connection. For CommonJS, use `const { Connection } = require('duckdb-async');`
• Statement
  wrong:

  const Statement = require('duckdb-async').Statement; // Less common CJS import pattern

  correct:

  import { Statement } from 'duckdb-async';

  Represents a prepared statement, offering Promise-based execution methods like `all`, `run`, and `get`. For CommonJS, use `const { Statement } = require('duckdb-async');`
• CommonJS require

  const { Database, Connection } = require('duckdb-async');

  For CommonJS environments, named exports are accessed via destructuring `require`.

Quickstart

Demonstrates connecting to an in-memory DuckDB database, executing a simple query, performing DDL/DML, and closing the connection using async/await.

import { Database } from "duckdb-async";

async function simpleTest() {
  const db = await Database.create(":memory:");
  // Example of using a query with parameters
  const rows = await db.all("select * from range(?,?)", 1, 10);
  console.log('Query Result:', rows);

  // Example of a run operation (e.g., DDL or DML without returning rows)
  await db.run("CREATE TABLE items (id INTEGER, name VARCHAR)");
  await db.run("INSERT INTO items VALUES (?, ?)", 1, 'Apple');
  await db.run("INSERT INTO items VALUES (?, ?)", 2, 'Banana');

  const allItems = await db.all("SELECT * FROM items");
  console.log('All Items:', allItems);

  // Close the database connection (important for file-based databases)
  await db.close();
}

simpleTest().catch(console.error);