Registry / database / databricks-sql-nodejs

databricks-sql-nodejs

library1.8.5jsnpmunverified

A Node.js driver for connecting to Databricks clusters and SQL warehouses via the Thrift API (HiveServer2 protocol). Current stable version is 1.8.5, with monthly releases. It is a fork of the Hive Driver, supporting both CommonJS and ESM. Key differentiators: direct Databricks SQL support, token-based authentication, and TypeScript types included. Note: this is a community fork (owens3364) that removes lz4 dependency for better Node 20 compatibility.

database

npm install databricks-sql-nodejs

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · DATABRICKS-SQL-NOD

databricks-sql-nodejs

databasejavascriptv1.8.5

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

DBSQLClient

✓ import { DBSQLClient } from 'databricks-sql-nodejs'

✗ const DBSQLClient = require('databricks-sql-nodejs').DBSQLClient

Package supports both CommonJS and ESM. Default export is not available; always use named import.

IDBSQLClient

✓ import type { IDBSQLClient } from 'databricks-sql-nodejs'

✗ import { IDBSQLClient } from 'databricks-sql-nodejs' (will cause runtime error in JS, only works as type import in TypeScript)

IDBSQLClient is a TypeScript interface, not a runtime value. Use import type to avoid issues.

DBSQLSession

✓ import { DBSQLSession } from 'databricks-sql-nodejs'

✗ const { DBSQLSession } = require('databricks-sql-nodejs')

Available as named export. CommonJS destructuring works but prefer ESM.

TStatusCode

✓ import { TStatusCode } from 'databricks-sql-nodejs/dist/Thrift/TCLIService_types'

✗ import { TStatusCode } from 'databricks-sql-nodejs'

TStatusCode is part of the internal Thrift types, not exported from the main package entry. Access via dist path or use DBSQLSession.TStatusCode.

Connects to a Databricks SQL warehouse, runs a query, and prints results as a table.

import { DBSQLClient } from 'databricks-sql-nodejs'; const client = new DBSQLClient(); const token = process.env.DATABRICKS_TOKEN ?? ''; const host = process.env.DATABRICKS_HOST ?? ''; const path = '/sql/2.0/warehouses/' + (process.env.DATABRICKS_WAREHOUSE_ID ?? ''); async function run() { try { await client.connect({ host, path, token }); const session = await client.openSession(); const queryOperation = await session.executeStatement('SELECT 1 AS id, \'Hello\' AS msg'); const result = await queryOperation.fetchAll(); console.table(result); await queryOperation.close(); await session.close(); await client.close(); } catch (error) { console.error(error); process.exit(1); } } run();

Debug

Known issues

breakingThe package has been forked from the official Databricks driver; the npm package 'databricks-sql-nodejs' on npm is now maintained by a third party (owens3364) and may diverge from Databricks' own releases.

fix

Use official 'databricks-sql-nodejs' if you need Databricks support, but verify the maintainer. Alternatively, use '@databricks/sql' for the official driver.

affects: >=1.8.4

deprecatedThe path format '/sql/2.0/warehouses/<warehouse_id>' is deprecated for new workspaces. Use '/sql/1.0/warehouses/<warehouse_id>' or the newer endpoint.

fix

Check your workspace's SQL endpoint documentation and use the correct path.

affects: >=1.0.0

gotchaDBSQLClient.connect() returns the client instance, but the promise resolves to the same client; be careful not to reassign the variable incorrectly.

fix

Use .then(client => { /* client is the same instance */ }) or async/await as shown in examples.

affects: >=1.0.0

gotchafetchAll() returns an array of rows, but each row is a plain object (not a Map) with column names as keys; order is not guaranteed if not specified in query.

fix

Always use ORDER BY in queries when row order is important.

affects: >=1.0.0

breakingThe package removed dependency on 'lz4' and '@types/lz4' starting from version 1.8.5. Any code relying on these modules may break.

fix

If you need lz4 compression, install it separately and configure thrift transport accordingly.

affects: >=1.8.5

Errors

Common errors & fixes

Error: connect ECONNREFUSED <host>:443

Incorrect hostname or network issue; Databricks SQL warehouse not accessible.

fix

Verify host and path. Ensure the SQL warehouse is running and your IP is allowed in the workspace's firewall settings.

Error: Invalid path provided. Path must start with '/sql/'

The path used in connect() does not match the expected format.

fix

Use the correct SQL warehouse path, e.g., '/sql/2.0/warehouses/warehouse-id'.

Error: [THRIFT] TProtocolException: Unexpected data

Server returned unexpected Thrift data, possibly due to protocol mismatch or server error.

fix

Update to the latest version of the driver. Check Databricks SQL warehouse status and try again.

TypeError: DBSQLClient is not a constructor

Using default import instead of named import (ESM only supports named exports).

fix

Change import to: import { DBSQLClient } from 'databricks-sql-nodejs' (note curly braces).

Upgrade

Version history

1.8.5latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

12 hits · last 30 days

node

Resources

githubhttps://github.com/owens3364/databricks-sql-nodejs ↗

packagedatabricks-sql-nodejs ↗

homepagehttps://github.com/owens3364/databricks-sql-nodejs#readme ↗