Haybarn Node Bindings & API

May 15, 2026 · View on GitHub

Node bindings to the DuckDB C API, plus a friendly API for using Haybarn — a derived distribution of DuckDB, powered by DuckDB — in Node applications.

This is a hard fork of duckdb/duckdb-node-neo. It links against Haybarn (libhaybarn) rather than upstream libduckdb, and its npm packages are published under the @haybarn scope. See NOTICE for what's been modified and the trademark attribution.

Packages

Documentation

Published

Use

import { DuckDBInstance } from '@haybarn/node-api';

const instance = await DuckDBInstance.create(':memory:');
const connection = await instance.connect();
const reader = await connection.runAndReadAll('select version()');
console.log(reader.getRows()); // [ [ 'v1.5.2' ] ]

The JavaScript API surface is unchanged from upstream — class names, method signatures, and return shapes are kept verbatim so migration is essentially a single import-source swap:

- import { DuckDBInstance } from '@duckdb/node-api';
+ import { DuckDBInstance } from '@haybarn/node-api';

See api/pkgs/@haybarn/node-api/README.md for the full API.

Development

Setup

Build & Test Bindings

  • cd bindings
  • pnpm run build (downloads libhaybarn-*.zip from Haybarn releases)
  • pnpm test

Build & Test API

  • cd api
  • pnpm run build
  • pnpm test

Update Package Versions

Bump version in:

  • api/pkgs/@haybarn/node-api/package.json
  • bindings/pkgs/@haybarn/node-bindings/package.json
  • bindings/pkgs/@haybarn/node-bindings-darwin-arm64/package.json
  • bindings/pkgs/@haybarn/node-bindings-darwin-x64/package.json
  • bindings/pkgs/@haybarn/node-bindings-linux-arm64/package.json
  • bindings/pkgs/@haybarn/node-bindings-linux-arm64-musl/package.json
  • bindings/pkgs/@haybarn/node-bindings-linux-x64/package.json
  • bindings/pkgs/@haybarn/node-bindings-linux-x64-musl/package.json
  • bindings/pkgs/@haybarn/node-bindings-win32-arm64/package.json
  • bindings/pkgs/@haybarn/node-bindings-win32-x64/package.json

Upgrade Haybarn / DuckDB Version

Change the release tag (haybarn-v<version>) and the inside-zip file names in each fetch script:

  • bindings/scripts/fetch_libhaybarn_linux_amd64.py
  • bindings/scripts/fetch_libhaybarn_linux_amd64_musl.py
  • bindings/scripts/fetch_libhaybarn_linux_arm64.py
  • bindings/scripts/fetch_libhaybarn_linux_arm64_musl.py
  • bindings/scripts/fetch_libhaybarn_osx_universal.py
  • bindings/scripts/fetch_libhaybarn_windows_amd64.py
  • bindings/scripts/fetch_libhaybarn_windows_arm64.py
  • bindings/test/constants.test.ts

Then bump the package versions as above.

Check Function Signatures

  • node scripts/checkFunctionSignatures.mjs [writeFiles]

Checks for differences between the function signatures in duckdb.h (kept upstream-named since it's the C API surface) and those declared in haybarn.d.ts and implemented in duckdb_node_bindings.cpp. Useful when rolling forward the Haybarn version to detect changes to the C API.

Publish Packages

Push a haybarn-v<version> tag (or use the Haybarn Node workflow_dispatch) to build on all platforms and publish all 10 @haybarn/* packages to npm.

Attribution

Haybarn is independent of and not endorsed by the DuckDB Foundation. DuckDB is a trademark of the DuckDB Foundation. See NOTICE for the modifications this fork makes to the upstream duckdb/duckdb-node-neo repository.