{"id":16009,"library":"duckdb-async","title":"DuckDB Async NodeJS Wrappers","description":"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.","status":"deprecated","version":"1.4.2","language":"javascript","source_language":"en","source_url":"https://github.com/motherduckdb/duckdb-async","tags":["javascript","duckdb","database","typescript","promise"],"install":[{"cmd":"npm install duckdb-async","lang":"bash","label":"npm"},{"cmd":"yarn add duckdb-async","lang":"bash","label":"yarn"},{"cmd":"pnpm add duckdb-async","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Runtime dependency for the underlying DuckDB NodeJS API.","package":"duckdb","optional":false}],"imports":[{"note":"The `Database` class is a named export. Its constructor is callback-based; use the static `Database.create()` method for an async, promise-based initialization.","wrong":"import Database from 'duckdb-async';","symbol":"Database","correct":"import { Database } from 'duckdb-async';"},{"note":"Provides Promise-based methods for executing SQL queries on an established database connection. For CommonJS, use `const { Connection } = require('duckdb-async');`","wrong":"const { Connection } = require('duckdb-async'); // Incorrect for modern ESM/TypeScript projects","symbol":"Connection","correct":"import { Connection } from 'duckdb-async';"},{"note":"Represents a prepared statement, offering Promise-based execution methods like `all`, `run`, and `get`. For CommonJS, use `const { Statement } = require('duckdb-async');`","wrong":"const Statement = require('duckdb-async').Statement; // Less common CJS import pattern","symbol":"Statement","correct":"import { Statement } from 'duckdb-async';"},{"note":"For CommonJS environments, named exports are accessed via destructuring `require`.","symbol":"CommonJS require","correct":"const { Database, Connection } = require('duckdb-async');"}],"quickstart":{"code":"import { Database } from \"duckdb-async\";\n\nasync function simpleTest() {\n  const db = await Database.create(\":memory:\");\n  // Example of using a query with parameters\n  const rows = await db.all(\"select * from range(?,?)\", 1, 10);\n  console.log('Query Result:', rows);\n\n  // Example of a run operation (e.g., DDL or DML without returning rows)\n  await db.run(\"CREATE TABLE items (id INTEGER, name VARCHAR)\");\n  await db.run(\"INSERT INTO items VALUES (?, ?)\", 1, 'Apple');\n  await db.run(\"INSERT INTO items VALUES (?, ?)\", 2, 'Banana');\n\n  const allItems = await db.all(\"SELECT * FROM items\");\n  console.log('All Items:', allItems);\n\n  // Close the database connection (important for file-based databases)\n  await db.close();\n}\n\nsimpleTest().catch(console.error);","lang":"typescript","description":"Demonstrates connecting to an in-memory DuckDB database, executing a simple query, performing DDL/DML, and closing the connection using async/await."},"warnings":[{"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.","message":"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`.","severity":"breaking","affected_versions":">=1.4.x"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"Attempting to instantiate `Database` directly with `new Database(...)`.","error":"TypeError: Cannot read properties of undefined (reading 'all') at new Database"},{"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 */ });`.","cause":"Attempting to use `await` or `.then()` directly on the `each` method, which is callback-based.","error":"TypeError: db.each(...).then is not a function"}],"ecosystem":"npm"}