DuckDB Node API

The DuckDB C API is transitioning from V1 to V2. This transition involves significant changes in how functions are named, how errors are reported, and how memory ownership is handled.

Features not yet available in V2

• Appender: There is no V2 counterpart for the Appender (used for bulk-append scenarios). The project intends to cover bulk-append scenarios using other methods.
• Conversion Helpers: Functions for converting Date, time, timestamp, hugeint, and decimal (e.g., duckdb_from_date, duckdb_to_timestamp) are absent in V2. Clients are expected to implement these as pure computation over plain structs. In the Node.js binding, these are implemented in TypeScript to avoid native round-trips.
• Memory Helpers: duckdb_vector_size and various malloc/free helpers are missing.
• Control Interfaces: Profiling info and Task/threading control (duckdb_execute_tasks) are not exposed in V2.
• Instance Cache: Subsumed by the new 'environment' concept, though the mapping is not one-to-one (DuckDBInstanceCache remains a public type in the API package).

Benefits of migrating to V2

• Typed Error Codes: Replaces message-string matching with structured error codes.
• Improved Type Safety: Function-info type tags become ordinary externals tags rather than guards against memory corruption.
• Efficient Data Access: Supports dictionary and constant vector reading without requiring a flatten operation.
• Async-Friendly Streaming: Uses WAITING-based streaming, which is better suited for async bindings than the V1 pending-result pump.
• Advanced Features: Provides better support for table function filter/projection pushdown, catalog/table description, and replacement scans.
• Standardized Identifiers: qname (qualified-name parsing/rendering) and identifier_render_quoted replace hand-rolled quoting logic.

To prevent long-running DuckDB tasks from blocking the Node.js event loop, you can use low-level methods to control task evaluation. This allows for better cooperative multithreading by splitting work into short tasks.

Recommended Approach: Use startStreamThenRead methods. These are the best options for cooperative multithreading because they create a streaming result (preventing full materialization) and use pending results to split processing into short tasks.

Low-level Approach:

1. Use prepared.startStream() to get a pending result.
2. Enter a loop checking pending.runTask() !== DuckDBPendingResultState.RESULT_READY.
3. Use await sleep(1) or similar inside the loop to yield control back to the Node.js event loop.
4. Once ready, call await pending.getResult().

import { DuckDBPendingResultState } from '@duckdb/node-api';

async function sleep(ms) {
  return new Promise((resolve) => {
    setTimeout(resolve, ms);
  });
}

const prepared = await connection.prepare('from range(10_000_000)');
const pending = prepared.startStream();
while (pending.runTask() !== DuckDBPendingResultState.RESULT_READY) {
  console.log('not ready');
  await sleep(1);
}
console.log('ready');
const result = await pending.getResult();

In DuckDB 2.0, deprecation of the V1 API is managed via compile-time switches rather than compiler warnings. This means that using deprecated V1 functions will not trigger warnings unless specific macros are defined.

Controlling Deprecation

• V1 Deprecation: Controlled by DUCKDB_API_ALLOW_DEPRECATED. It defaults to 1. If you want to ensure you are not using deprecated V1 features, you can define DUCKDB_API_NO_DEPRECATED.
• V2 Deprecation: Controlled by DUCKDB_V2_API_ALLOW_DEPRECATED, which also defaults to 1.
• Node Neo Behavior: By default, Node Neo does not define these switches, so the defaults apply and all V1/V2 calls compile without warnings.

Pinning API Versions

Every declaration in the V1 header is now wrapped in a DUCKDB_API_VERSION_AT_LEAST(major, minor, patch) guard. To pin your application to an older surface, you can define the following macros:

• DUCKDB_API_VERSION_MAJOR
• DUCKDB_API_VERSION_MINOR
• DUCKDB_API_VERSION_PATCH

If not defined, the targeted version defaults to 1.5.6.