duckdb-async

library1.4.2jsnpmunverified

duckdb-async provides Promise-based and TypeScript-first wrappers for the DuckDB NodeJS API, allowing developers to interact with DuckDB databases using modern `async/await` patterns instead of traditional callbacks. Currently at version 1.4.2, its releases have historically aligned with the `duckdb-node` module, which it depends on. A key differentiator is its comprehensive TypeScript support and the conversion of most callback-driven methods in `duckdb-node`'s `Database`, `Connection`, and `Statement` classes into promise-returning equivalents. Notably, the `Database` constructor is replaced by a static `Database.create()` factory method to accommodate async initialization. However, it's critical to note that `duckdb-async` is currently in a deprecated state; the maintainers have announced that it, along with `duckdb-node`, will not be released for DuckDB 1.5.x (~Early 2026) and subsequent versions. Users are advised to migrate to the newer `@duckdb/node-api` package for ongoing support and future compatibility.

database serialization

npm install duckdb-async

github ↗package ↗

INSTALL

IMPORT

SIG · DUCKDB-ASYNC

duckdb-async

databasejavascriptv1.4.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Database

✓ import { Database } from 'duckdb-async';

✗ 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

✓ import { Connection } from 'duckdb-async';

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

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

Statement

✓ import { Statement } from 'duckdb-async';

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

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`.

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);

Debug

Known issues

breakingThe `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.

affects: >=1.4.x

gotchaThe `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.

affects: >=1.0.0

Errors

Common errors & fixes

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

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

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 */ });`.

Upgrade

Version history

1.4.2latest on npm

Audit

Dependencies

duckdbrequiredRuntime dependency for the underlying DuckDB NodeJS API.

Agent activity

7 hits · last 30 days

node

Bingbot

Resources

githubhttps://github.com/motherduckdb/duckdb-async ↗

packagehttps://www.npmjs.com/package/duckdb-async ↗