# Databricks SQL Driver for Node.js

![http://www.apache.org/licenses/LICENSE-2.0.txt](http://img.shields.io/:license-Apache%202-brightgreen.svg)
[![npm](https://img.shields.io/npm/v/@databricks/sql?color=blue&style=flat)](https://www.npmjs.com/package/@databricks/sql)
[![test](https://github.com/databricks/databricks-sql-nodejs/workflows/test/badge.svg?branch=main)](https://github.com/databricks/databricks-sql-nodejs/actions?query=workflow%3Atest+branch%3Amain)
[![coverage](https://codecov.io/gh/databricks/databricks-sql-nodejs/branch/main/graph/badge.svg)](https://codecov.io/gh/databricks/databricks-sql-nodejs)

## 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](https://github.com/lenchv/hive-driver) which connects via Thrift API.

## Requirements

- Node.js 22.23.4+, 24.22.1+, 26.12.1+, or a later release

## Installation

```bash
npm i @databricks/sql
```

## Usage

[examples/usage.js](examples/usage.js)

```javascript
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);
  });
```

### Automatic cleanup with `await using`

The client, sessions, and operations implement `Symbol.asyncDispose`. On scope exit, `await using` calls `close()`,
including when the block throws. Disposal follows the existing `close()` behavior, and cleanup errors propagate.
If both the block and a disposal fail, `await using` throws a `SuppressedError` containing both errors.
Node.js 24+ supports
`await using` natively; on Node.js 22, compile it with TypeScript 5.2+. TypeScript also needs the disposable
declarations (such as the global `AsyncDisposable` type) to compile `await using`: if your typings don't already
provide them, add `"esnext.disposable"` (or `"esnext"`) to `compilerOptions.lib` in your `tsconfig.json`, otherwise the
example below can fail to compile even with TypeScript 5.2+.

`openSession()` and the session's operation methods are typed as returning the `IDBSQLSession` and `IOperation`
interfaces, which don't require `Symbol.asyncDispose` (so existing custom implementations keep compiling). In
TypeScript, wrap their results with `asyncDisposable()`: it returns the driver's own sessions and operations unchanged,
typed as disposable.

```typescript
import { DBSQLClient, asyncDisposable } from '@databricks/sql';

async function main() {
  await using client = new DBSQLClient();
  await client.connect({ host, path, token });

  await using session = asyncDisposable(await client.openSession());
  await using operation = asyncDisposable(await session.executeStatement('SELECT "Hello, World!"'));
  console.table(await operation.fetchAll());
} // disposes `operation`, `session`, then `client`
```

## Configuration

See [CONNECTION_PARAMETERS.md](CONNECTION_PARAMETERS.md) for every connection,
session, and per-statement parameter the driver accepts, and whether each one
applies to the Thrift backend (default), the SEA backend, or both.

## Telemetry

The driver emits connection, statement, and CloudFetch metrics plus
redacted error events to help Databricks improve driver reliability. No
SQL text, parameter values, or row data is ever collected. Emission is
gated by a server-side feature flag and can be disabled per-connection
with `telemetryEnabled: false` or globally with the
`DATABRICKS_TELEMETRY_DISABLED` env var.

See [docs/TELEMETRY.md](docs/TELEMETRY.md) for the full event payloads,
tuning knobs, multi-tenant guidance, and troubleshooting.

## Run Tests

### Unit tests

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

```bash
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:

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

Then run

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

## Contributing

See [CONTRIBUTING.md](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](LICENSE)