Arrow Flight SQL JS

Arrow Flight SQL client for JavaScript and TypeScript runtimes.

SQL-specific functionality on top of Arrow Flight for database interactions. Built on @qualithm/arrow-flight-js as a peer dependency.

Features

• Full Arrow Flight SQL protocol support
• Query execution with Apache Arrow result sets
• Prepared statements with parameter binding
• Transaction support (begin, commit, rollback)
• Database metadata queries (catalogs, schemas, tables, keys)
• Query cancellation
• TypeScript-first with comprehensive type definitions
• Cross-runtime: Bun, Node.js 20+, Deno
• Streaming results with async iterables
• Comprehensive error handling with typed error codes
• ESM-only, tree-shakeable

Installation

npm install @qualithm/arrow-flight-sql-js @qualithm/arrow-flight-js apache-arrow
# or
bun add @qualithm/arrow-flight-sql-js @qualithm/arrow-flight-js apache-arrow

Note: @qualithm/arrow-flight-js is a peer dependency and must be installed separately.

Quick Start

import { createFlightSqlClient, queryToTable } from "@qualithm/arrow-flight-sql-js"

const client = await createFlightSqlClient({
  host: "localhost",
  port: 8815,
  tls: false
})

const table = await queryToTable(client, "SELECT * FROM users WHERE active = true")
console.log("Rows:", table.numRows)

for (const row of table) {
  console.log(JSON.stringify(row))
}

client.close()

See the examples directory for complete, runnable demonstrations.

Examples

Example	Description
basic-query.ts	Simple query execution with queryToTable()
authentication.ts	Basic auth, bearer tokens, connection patterns
updates.ts	INSERT, UPDATE, DELETE operations
streaming-results.ts	Process large datasets with iterateResults()
prepared-statements.ts	Parameterised queries and updates
transactions.ts	Atomic operations with commit/rollback
metadata-queries.ts	Catalogs, schemas, tables, keys, SQL info
cancellation.ts	Cancel long-running queries
error-handling.ts	FlightSqlError and FlightError handling

API Reference

Query Execution

Method	Description
query()	Execute a SQL query, get FlightInfo
executeUpdate()	Execute INSERT/UPDATE/DELETE
executePreparedQuery()	Execute a prepared statement query
executePreparedUpdate()	Execute a prepared statement update

Prepared Statements

Method	Description
createPreparedStatement()	Create a new prepared statement
closePreparedStatement()	Close and release a prepared statement
bindParameters()	Bind parameter values

Transactions

Method	Description
beginTransaction()	Start a new transaction
commit()	Commit a transaction
rollback()	Roll back a transaction
endTransaction()	End transaction (low-level)

Metadata

Method	Description
getCatalogs()	List available catalogs
getDbSchemas()	List database schemas
getTables()	List tables with optional filtering
getTableTypes()	List supported table types
getPrimaryKeys()	Get primary key info for a table
getExportedKeys()	Get foreign keys referencing a table
getImportedKeys()	Get foreign keys from a table
getCrossReference()	Get foreign keys between two tables
getSqlInfo()	Get SQL dialect/server capabilities
getXdbcTypeInfo()	Get supported data types

Result Utilities

Function	Description
queryToTable()	Execute query, return Arrow Table
flightInfoToTable()	Convert FlightInfo to Arrow Table
ticketToTable()	Get single ticket data as Arrow Table
iterateResults()	Stream results as async iterable

Cancellation

Method	Description
cancelFlightInfo()	Cancel a running query

Development

Prerequisites

• Bun (recommended), Node.js 20+, or Deno

Setup

bun install

Building

bun run build

Testing

# Unit tests
bun test

# Integration tests (requires running Arrow Flight SQL server)
FLIGHT_HOST=localhost FLIGHT_PORT=50051 bun run test:integration

Benchmarks

# Requires running Arrow Flight SQL server
FLIGHT_HOST=localhost FLIGHT_PORT=50051 bun run bench

Linting & Formatting

bun run lint
bun run format
bun run typecheck

License

Apache-2.0