# harlequin-databricks
[](https://pypi.org/project/harlequin-databricks/)
[](https://anaconda.org/conda-forge/harlequin-databricks)
[](https://pypi.org/project/harlequin-databricks/)
[](https://github.com/alexmalins/harlequin-databricks/actions/workflows/code_quality_checks.yml)
[](https://github.com/astral-sh/ruff)
[](https://github.com/alexmalins/harlequin-databricks/blob/main/LICENSE)
[](https://pepy.tech/project/harlequin-databricks)
A [Harlequin](https://harlequin.sh) adapter for Databricks. Supports connecting to Databricks SQL
warehouses or Databricks Runtime (DBR) interactive clusters.
<img src="img/harlequin_databricks.jpg" alt="harlequin-databricks" width="945">
## Installation
`harlequin-databricks` depends on `harlequin`, so installing this package using any of the methods
below will also install `harlequin`.
### Using uv
The recommended way to install `harlequin-databricks` is using `uv`:
```bash
uv tool install harlequin --with harlequin-databricks
```
This command will install `harlequin` with the databricks adapter into an isolated environment and
add it to your PATH so you can easily run the executable.
### Alternative installation methods
Alternatively, if you know what you're doing, after installing Python 3.9 or above, install
`harlequin-databricks` using pip, pipx, poetry, or any other program that can install Python
packages from PyPI. For example:
```bash
pip install harlequin-databricks
```
## Connecting to Databricks
To connect to Databricks you are going to need to provide as CLI arguments:
- server-hostname
- http-path
- credentials for one of the following authentication methods:
- a personal access token (PAT)
- a username and password
- an OAuth U2M type
- a service principle client ID and secret for OAuth M2M
### Personal Access Token (PAT) authentication:
```bash
harlequin -a databricks --server-hostname ***.cloud.databricks.com --http-path /sql/1.0/endpoints/*** --access-token dabpi***
```
### Username and password (basic) authentication:
```bash
harlequin -a databricks --server-hostname ***.cloud.databricks.com --http-path /sql/1.0/endpoints/*** --username *** --password ***
```
### OAuth U2M authentication:
For [OAuth user-to-machine (U2M) authentication](https://docs.databricks.com/en/dev-tools/python-sql-connector.html#auth-u2m)
supply either `databricks-oauth` or `azure-oauth` to the `--auth-type` CLI argument:
```bash
harlequin -a databricks --server-hostname ***.cloud.databricks.com --http-path /sql/1.0/endpoints/*** --auth-type databricks-oauth
```
### OAuth M2M authentication:
For [OAuth machine-to-machine (M2M) authentication](https://docs.databricks.com/en/dev-tools/python-sql-connector.html#oauth-machine-to-machine-m2m-authentication)
you need to `pip install databricks-sdk` as an additional dependency
([databricks-sdk](https://github.com/databricks/databricks-sdk-py) is an optional dependency of
`harlequin-databricks`) and supply `--client-id` and `--client-secret` CLI arguments:
```bash
harlequin -a databricks --server-hostname ***.cloud.databricks.com --http-path /sql/1.0/endpoints/*** --client-id *** --client-secret ***
```
## Store an alias for your connection string
We recommend you include an alias for your connection string in your `.bash_profile`/`.zprofile` so
you can launch harlequin-databricks with a short command like `hdb` each time.
Run this command
(once) to create the alias:
```bash
echo 'alias hdb="harlequin -a databricks --server-hostname ***.cloud.databricks.com --http-path /sql/1.0/endpoints/*** --access-token dabpi***"' >> .bash_profile
```
## Using Unity Catalog and want fast Data Catalog indexing?
Supply the `--skip-legacy-indexing` command line flag if you do not care about legacy metastores
(e.g. `hive_metastore`) being indexed in Harlequin's Data Catalog pane.
This flag will skip indexing of old non-Unity Catalog metastores (i.e. they won't appear in the
Data Catalog pane with this flag).
Because of the way legacy Databricks metastores works, a separate SQL query is required to fetch
the metadata of each table in a legacy metastore. This means indexing them for Harlequin's Data Catalog pane is slow.
Databricks's Unity Catalog upgrade brought
[Information Schema](https://docs.databricks.com/en/sql/language-manual/sql-ref-information-schema.html),
which allows harlequin-databricks to fetch metadata for all Unity Catalog assets with only two SQL queries.
So if your Databricks instance is running Unity Catalog, and you no longer care about the legacy
metastores, setting the `--skip-legacy-indexing` CLI flag is recommended as it will mean
much faster indexing & refreshing of the assets in the Data Catalog pane.
## Initialization Scripts
Each time you start Harlequin, it will execute SQL commands from a Databricks initialization script.
For example:
```sql
USE CATALOG my_catalog;
SET TIME ZONE 'Asia/Tokyo';
DECLARE yesterday DATE DEFAULT CURRENT_DATE - INTERVAL '1' DAY;
```
Multi-line SQL is allowed, but must be terminated by a semicolon.
### Configuring the Script Location
By default, Harlequin will execute the script found at `~/.databricksrc`. However, you can provide
a different path using the `--init-path` option (aliased to `-i` or `-init`):
```bash
harlequin -a databricks --init-path /path/to/my/script.sql
```
### Disabling Initialization
If you would like to open Harlequin without running the script you have at `~/.databricksrc`, you
can either pass a nonexistent path (or `/dev/null`) to the option above, or start Harlequin with
the `--no-init` option:
```bash
harlequin -a databricks --no-init
```
## Other CLI options:
For more details on other command line options, run:
```bash
harlequin --help
```
For more information, see the
[harlequin-databricks Docs](https://harlequin.sh/docs/databricks/index).
## Issues, Contributions and Feature Requests
Please report bugs/issues with this adapter via the GitHub
[issues](https://github.com/alexmalins/harlequin-databricks/issues) page. You are welcome to
attempt fixes yourself by forking this repo then opening a [PR](https://github.com/alexmalins/harlequin-databricks/pulls).
For feature suggestions, please post in the
[discussions](https://github.com/alexmalins/harlequin-databricks/discussions).
## Special thanks to...
[Ted Conbeer](https://github.com/tconbeer), [Josh Temple](https://github.com/joshtemple) &
[Tyler Hillery](https://github.com/TylerHillery).
Raw data
{
"_id": null,
"home_page": null,
"name": "harlequin-databricks",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.14.0,>=3.9",
"maintainer_email": null,
"keywords": "harlequin, harlequin-databricks, databricks, sql, terminal, ide, database, data warehouse, data lake",
"author": "Alex Malins, Zach Shirah",
"author_email": "Alex Malins <github@alexmalinsREMOVETHIS.com>, Zach Shirah <zachshirah01@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/ca/9d/b5a5a9e18864a29b3d38cce3d5034f940db390508ceacfe33f7018a5196d/harlequin_databricks-0.6.2.tar.gz",
"platform": null,
"description": "# harlequin-databricks\n\n[](https://pypi.org/project/harlequin-databricks/)\n[](https://anaconda.org/conda-forge/harlequin-databricks)\n[](https://pypi.org/project/harlequin-databricks/)\n[](https://github.com/alexmalins/harlequin-databricks/actions/workflows/code_quality_checks.yml)\n[](https://github.com/astral-sh/ruff)\n[](https://github.com/alexmalins/harlequin-databricks/blob/main/LICENSE)\n[](https://pepy.tech/project/harlequin-databricks)\n\nA [Harlequin](https://harlequin.sh) adapter for Databricks. Supports connecting to Databricks SQL\nwarehouses or Databricks Runtime (DBR) interactive clusters.\n\n<img src=\"img/harlequin_databricks.jpg\" alt=\"harlequin-databricks\" width=\"945\">\n\n\n## Installation\n\n`harlequin-databricks` depends on `harlequin`, so installing this package using any of the methods\nbelow will also install `harlequin`.\n\n### Using uv\n\nThe recommended way to install `harlequin-databricks` is using `uv`:\n\n```bash\nuv tool install harlequin --with harlequin-databricks\n```\n\nThis command will install `harlequin` with the databricks adapter into an isolated environment and\nadd it to your PATH so you can easily run the executable.\n\n### Alternative installation methods\n\nAlternatively, if you know what you're doing, after installing Python 3.9 or above, install\n`harlequin-databricks` using pip, pipx, poetry, or any other program that can install Python\npackages from PyPI. For example:\n\n```bash\npip install harlequin-databricks\n```\n\n\n## Connecting to Databricks\n\nTo connect to Databricks you are going to need to provide as CLI arguments:\n\n- server-hostname\n- http-path\n- credentials for one of the following authentication methods:\n - a personal access token (PAT)\n - a username and password\n - an OAuth U2M type\n - a service principle client ID and secret for OAuth M2M\n\n\n### Personal Access Token (PAT) authentication:\n\n```bash\nharlequin -a databricks --server-hostname ***.cloud.databricks.com --http-path /sql/1.0/endpoints/*** --access-token dabpi***\n```\n\n### Username and password (basic) authentication:\n\n```bash\nharlequin -a databricks --server-hostname ***.cloud.databricks.com --http-path /sql/1.0/endpoints/*** --username *** --password ***\n```\n\n### OAuth U2M authentication:\n\nFor [OAuth user-to-machine (U2M) authentication](https://docs.databricks.com/en/dev-tools/python-sql-connector.html#auth-u2m)\nsupply either `databricks-oauth` or `azure-oauth` to the `--auth-type` CLI argument:\n\n```bash\nharlequin -a databricks --server-hostname ***.cloud.databricks.com --http-path /sql/1.0/endpoints/*** --auth-type databricks-oauth\n```\n\n### OAuth M2M authentication:\n\nFor [OAuth machine-to-machine (M2M) authentication](https://docs.databricks.com/en/dev-tools/python-sql-connector.html#oauth-machine-to-machine-m2m-authentication)\nyou need to `pip install databricks-sdk` as an additional dependency\n([databricks-sdk](https://github.com/databricks/databricks-sdk-py) is an optional dependency of\n`harlequin-databricks`) and supply `--client-id` and `--client-secret` CLI arguments:\n\n```bash\nharlequin -a databricks --server-hostname ***.cloud.databricks.com --http-path /sql/1.0/endpoints/*** --client-id *** --client-secret ***\n```\n\n\n## Store an alias for your connection string\n\nWe recommend you include an alias for your connection string in your `.bash_profile`/`.zprofile` so\nyou can launch harlequin-databricks with a short command like `hdb` each time.\n\nRun this command\n(once) to create the alias:\n\n```bash\necho 'alias hdb=\"harlequin -a databricks --server-hostname ***.cloud.databricks.com --http-path /sql/1.0/endpoints/*** --access-token dabpi***\"' >> .bash_profile \n```\n\n\n## Using Unity Catalog and want fast Data Catalog indexing?\n\nSupply the `--skip-legacy-indexing` command line flag if you do not care about legacy metastores\n(e.g. `hive_metastore`) being indexed in Harlequin's Data Catalog pane.\n\nThis flag will skip indexing of old non-Unity Catalog metastores (i.e. they won't appear in the\nData Catalog pane with this flag).\n\nBecause of the way legacy Databricks metastores works, a separate SQL query is required to fetch\nthe metadata of each table in a legacy metastore. This means indexing them for Harlequin's Data Catalog pane is slow.\n\nDatabricks's Unity Catalog upgrade brought\n[Information Schema](https://docs.databricks.com/en/sql/language-manual/sql-ref-information-schema.html),\nwhich allows harlequin-databricks to fetch metadata for all Unity Catalog assets with only two SQL queries.\n\nSo if your Databricks instance is running Unity Catalog, and you no longer care about the legacy\nmetastores, setting the `--skip-legacy-indexing` CLI flag is recommended as it will mean\nmuch faster indexing & refreshing of the assets in the Data Catalog pane.\n\n\n## Initialization Scripts\n\nEach time you start Harlequin, it will execute SQL commands from a Databricks initialization script.\nFor example:\n\n```sql\nUSE CATALOG my_catalog;\nSET TIME ZONE 'Asia/Tokyo';\nDECLARE yesterday DATE DEFAULT CURRENT_DATE - INTERVAL '1' DAY;\n```\n\nMulti-line SQL is allowed, but must be terminated by a semicolon.\n\n### Configuring the Script Location\n\nBy default, Harlequin will execute the script found at `~/.databricksrc`. However, you can provide\na different path using the `--init-path` option (aliased to `-i` or `-init`):\n\n```bash\nharlequin -a databricks --init-path /path/to/my/script.sql\n```\n\n### Disabling Initialization\n\nIf you would like to open Harlequin without running the script you have at `~/.databricksrc`, you\ncan either pass a nonexistent path (or `/dev/null`) to the option above, or start Harlequin with\nthe `--no-init` option:\n\n```bash\nharlequin -a databricks --no-init\n```\n\n\n## Other CLI options:\n\nFor more details on other command line options, run:\n\n```bash\nharlequin --help\n```\n\nFor more information, see the\n[harlequin-databricks Docs](https://harlequin.sh/docs/databricks/index).\n\n\n## Issues, Contributions and Feature Requests\n\nPlease report bugs/issues with this adapter via the GitHub\n[issues](https://github.com/alexmalins/harlequin-databricks/issues) page. You are welcome to\nattempt fixes yourself by forking this repo then opening a [PR](https://github.com/alexmalins/harlequin-databricks/pulls).\n\nFor feature suggestions, please post in the\n[discussions](https://github.com/alexmalins/harlequin-databricks/discussions).\n\n\n## Special thanks to...\n\n[Ted Conbeer](https://github.com/tconbeer), [Josh Temple](https://github.com/joshtemple) &\n[Tyler Hillery](https://github.com/TylerHillery).\n",
"bugtrack_url": null,
"license": null,
"summary": "A Harlequin adapter for Databricks.",
"version": "0.6.2",
"project_urls": {
"Changelog": "https://github.com/alexmalins/harlequin-databricks/blob/main/CHANGELOG.md",
"Discussions": "https://github.com/alexmalins/harlequin-databricks/discussions",
"Documentation": "https://harlequin.sh/docs/databricks/index",
"Homepage": "https://harlequin.sh/docs/databricks/index",
"Issues": "https://github.com/alexmalins/harlequin-databricks/issues",
"Repository": "https://github.com/alexmalins/harlequin-databricks"
},
"split_keywords": [
"harlequin",
" harlequin-databricks",
" databricks",
" sql",
" terminal",
" ide",
" database",
" data warehouse",
" data lake"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "48e313d8c071d76ca3427e39e097cab2c9bf2a7db98cc9c7d2aa4d5757f8bac7",
"md5": "afe6c7c9a4e5d7614ae63b717b934b2b",
"sha256": "053fbdca714ecb30a4804b06860371b6eff505f5c05fca24f1908c6e5f36295e"
},
"downloads": -1,
"filename": "harlequin_databricks-0.6.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "afe6c7c9a4e5d7614ae63b717b934b2b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.14.0,>=3.9",
"size": 25958,
"upload_time": "2025-07-10T12:47:26",
"upload_time_iso_8601": "2025-07-10T12:47:26.855059Z",
"url": "https://files.pythonhosted.org/packages/48/e3/13d8c071d76ca3427e39e097cab2c9bf2a7db98cc9c7d2aa4d5757f8bac7/harlequin_databricks-0.6.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ca9db5a5a9e18864a29b3d38cce3d5034f940db390508ceacfe33f7018a5196d",
"md5": "6e548753413ed44da3cbf7a284143c3e",
"sha256": "330adf1b74bb6ed9a31659a816fe158f69405783fcd00fba9e31261d0f8cd503"
},
"downloads": -1,
"filename": "harlequin_databricks-0.6.2.tar.gz",
"has_sig": false,
"md5_digest": "6e548753413ed44da3cbf7a284143c3e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.14.0,>=3.9",
"size": 24108,
"upload_time": "2025-07-10T12:47:27",
"upload_time_iso_8601": "2025-07-10T12:47:27.977009Z",
"url": "https://files.pythonhosted.org/packages/ca/9d/b5a5a9e18864a29b3d38cce3d5034f940db390508ceacfe33f7018a5196d/harlequin_databricks-0.6.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-10 12:47:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "alexmalins",
"github_project": "harlequin-databricks",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "harlequin-databricks"
}
JSON
