Skip to content

Latest commit

 

History

History

README.md

Apache Arrow ADBC: Node.js Driver Manager

Node.js bindings for the Arrow Database Connectivity (ADBC) standard. Built on a native NAPI addon — requires Node.js 22+ and does not support browser or Deno environments. Bun is not officially tested.

Alpha. APIs may change without notice. If you try this and run into issues or have feedback, please open an issue.

Installation

npm install @apache-arrow/adbc-driver-manager apache-arrow

Usage

The driver option accepts either a full path to a shared library or a short name. When using a short name, the driver manager searches system and user paths for a matching ADBC driver manifest or library.

import { AdbcDatabase } from '@apache-arrow/adbc-driver-manager'

// Short name (resolves from system/user paths)
const db = new AdbcDatabase({ driver: 'sqlite' })
// Or a full path to a driver shared library
const db = new AdbcDatabase({ driver: '/path/to/libadbc_driver_sqlite.dylib' })

Once you have a database, open a connection and run queries:

const connection = await db.connect()

// Execute a query — returns an Apache Arrow Table
const table = await connection.query('SELECT 1 AS value')
console.log(table.toArray())

// For large result sets, stream record batches instead
const reader = await connection.queryStream('SELECT * FROM large_table')
for await (const batch of reader) {
  console.log(`Received batch with ${batch.numRows} rows`)
}

// DML — returns the number of affected rows
const affected = await connection.execute('DELETE FROM my_table WHERE id = 1')

await connection.close()
await db.close()

For finer-grained control, use the statement API directly:

import { tableFromArrays } from 'apache-arrow'

const stmt = await connection.createStatement()
await stmt.setSqlQuery('SELECT * FROM my_table WHERE id = ?')
await stmt.bind(tableFromArrays({ id: [42] }))
const reader = await stmt.executeQuery()
for await (const batch of reader) {
  console.log(batch.toArray())
}
await stmt.close()

Development

Prerequisites

  • Node.js 22+
  • Rust (latest stable)
  • CMake 3.14+ and a C/C++ compiler (for building the driver libraries)
  • npm (usually comes with Node.js)

Building from Source

  1. Install dependencies:

    npm install
  2. Build the Rust addon:

    npm run build:debug   # debug build (faster)
    npm run build         # release build

Testing

The tests require a built ADBC driver library (e.g. SQLite). Build everything including the SQLite driver with:

npm run build:driver

This runs CMake to compile the C ADBC drivers into build/lib/ and builds the Rust Node.js addon. Once built, run the tests:

npm test

License

Apache-2.0