Databricks SQL Driver for Node.js

Description

The Databricks SQL Driver for Node.js is a Javascript driver for applications that connect to Databricks clusters and SQL warehouses. This project is a fork of Hive Driver which connects via Thrift API.

Requirements

• Node.js 14 or newer

Installation

npm i @databricks/sql

Usage

examples/usage.js

const { DBSQLClient } = require('@databricks/sql');

const client = new DBSQLClient();

client
  .connect({
    host: '********.databricks.com',
    path: '/sql/2.0/warehouses/****************',
    token: 'dapi********************************',
  })
  .then(async (client) => {
    const session = await client.openSession();

    const queryOperation = await session.executeStatement('SELECT "Hello, World!"');
    const result = await queryOperation.fetchAll();
    await queryOperation.close();

    console.table(result);

    await session.close();
    await client.close();
  })
  .catch((error) => {
    console.log(error);
  });

Telemetry

The Databricks SQL Driver for Node.js includes an opt-in telemetry system that collects driver usage metrics and performance data to help improve the driver. Telemetry is disabled by default and follows a privacy-first design.

Key Features

• Privacy-first: No SQL queries, results, or sensitive data is ever collected
• Opt-in: Controlled by server-side feature flag (disabled by default)
• Non-blocking: All telemetry operations are asynchronous and never impact your queries
• Resilient: Circuit breaker protection prevents telemetry failures from affecting your application

What Data is Collected?

When enabled, the driver collects:

• ✅ Driver version and configuration settings
• ✅ Query performance metrics (latency, chunk counts, bytes downloaded)
• ✅ Error types and status codes
• ✅ Feature usage (CloudFetch, Arrow format, compression)

Never collected:

• ❌ SQL query text
• ❌ Query results or data values
• ❌ Table/column names or schema information
• ❌ User credentials or personal information

Configuration

To enable or disable telemetry explicitly:

const client = new DBSQLClient({
  telemetryEnabled: true, // Enable telemetry (default: false)
});

// Or override per connection:
await client.connect({
  host: '********.databricks.com',
  path: '/sql/2.0/warehouses/****************',
  token: 'dapi********************************',
  telemetryEnabled: false, // Disable for this connection
});

For detailed documentation including configuration options, event types, troubleshooting, and privacy details, see docs/TELEMETRY.md.

Run Tests

Unit tests

You can run all unit tests, or specify a specific test to run:

npm test
npm test -- <path/to/file.test.js>

e2e tests

Before running end-to-end tests, create a file named tests/e2e/utils/config.local.js and set the Databricks SQL connection info:

{
    host: '***.databricks.com',
    path: '/sql/2.0/warehouses/***',
    token: 'dapi***',
    database: ['catalog', 'database'],
}

Then run

npm run e2e
npm run e2e -- <path/to/file.test.js>

Contributing

See CONTRIBUTING.md

Issues

If you find any issues, feel free to create an issue or send a pull request directly.

License

Apache License 2.0