Harlequin
The SQL IDE for Your Terminal.
Installing Harlequin
Harlequin is a Python program, and there are many ways to install and run it. We strongly recommend using uv:
-
Install uv. From a POSIX shell, run:
curl -LsSf https://astral.sh/uv/install.sh | sh
Or using Windows Powershell:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
-
Install Harlequin as a tool using
uv:uv tool install harlequin
This command will install Harlequin into an isolated environment and add it to your PATH so you can easily run the executable.
Other Installation Methods
Alternatively, if you know what you're doing, after installing Python 3.9 or above, install Harlequin using pip, pipx, poetry, or any other program that can install Python packages from PyPI:
pip install harlequin
There is also a Homebrew formula for Harlequin, although this is maintained by the community and is not as rigorously tested as the Python installations. Note that the formula includes several Harlequin adapter packages (Postgres, MySQL/MariaDB, and ODBC) and their dependencies, which is convenient but increases the application size.
brew install harlequin
Installing Database Adapters
Harlequin can connect to dozens of databases using adapter plug-ins. Adapters are distributed as their own Python packages that need to be installed into the same environment as Harlequin.
For a list of known adapters provided either by the Harlequin maintainers or the broader community, see the adapters page.
The adapter docs also include installation instructions. Some adapters can be installed as Harlequin extras, like postgres. If you used uv to install Harlequin:
uv tool install 'harlequin[postgres]'
You can install multiple extras:
uv tool install 'harlequin[postgres,mysql,s3]'
Running Harlequin
Once Harlequin is installed, you run it from the command line. The arguments and options you pass in at the command line affect Harlequin's behavior, like what database adapter it uses, which database it connects to, whether or not the file picker is visible, and more. Assuming you have installed Harlequin so that it is on your PATH (uv tool install harlequin does this automatically), you run Harlequin by typing a command of this form into your shell:
harlequin [OPTIONS] [CONN_STR]
where [OPTIONS] is 0 or more pairs of the form --[option-name] [option-value], and [CONN_STR] is 0 or more connection strings. [OPTIONS] are composed of both Harlequin options and adapter options. For a full list of options, run Harlequin with the --help option:
harlequin --help
Using Harlequin with DuckDB
Harlequin defaults to using its DuckDB database adapter, which ships with Harlequin and includes the full DuckDB in-process database.
To open an in-memory DuckDB session, run Harlequin with no arguments:
harlequin
To open one or more DuckDB database files, pass in relative or absolute paths as connection strings (Harlequin will create DuckDB databases if they do not exist):
harlequin "path/to/duck.db" "another_duck.db"
Using Harlequin with SQLite and Other Adapters
Harlequin also ships with a SQLite3 adapter. To use that adapter, you specify the --adapter sqlite option. Like DuckDB, you can open an in-memory SQLite database by omitting the connection string:
harlequin --adapter sqlite
You can open one or more SQLite database files by passing in their paths as connection strings; note that the --adapter option has a short alias, -a:
harlequin -a sqlite "path/to/sqlite.db" "another_sqlite.db"
Other adapters can be installed as plug-ins; for more information, see the installation guide, and the guides for individual adapters. Each adapter can define its own options, which you can view using harlequin --help.
Configuring Harlequin
Harlequin contains a large number of options that allow you to set the theme, customize key bindings, show remote and local files, set the locale for number formatting, and much more. These can always be entered at the command line, but it can be convenient to define a configuration as a profile instead. For more information on configuring Harlequin, see Using Config Files.
A profile's string values can name environment variables — password = "${MYPASSWORD}", or ${MYHOST:-localhost} to supply a default — so a config file your team shares holds no credentials, and values an adapter declares as secrets are masked wherever Harlequin prints them. hsql, Harlequin's companion CLI (below), reads the same files and can report on them, with hsql --config show, --config validate and --config schema.
Using Harlequin with Agents or in Scripts
Harlequin has a companion CLI, hsql, that uses the same adapters and config files, but is optimized for headless use by agents and in automations. hsql is packaged with Harlequin (no additional installation required):
$ hsql -P dev -c "select * from users"
id | name
----+---------
1 | Ted
2 | Patrick
(2 rows)
hsql can also explore the catalog without writing SQL: hsql --catalog --path mydb.analytics lists a schema's relations (and --path mydb.analytics.orders lists that table's columns), while hsql --catalog-search customer_id searches every level at once.
To bound what an agent can do, --read-only connects in a mode the database refuses writes in, and hsql --timeout 30 cancels a run that takes longer than that. Both are also profile keys, and both refuse to start if the adapter cannot enforce them. Harlequin takes --read-only too.
For more information on hsql, see the getting started docs.
Using Harlequin with Django
django-harlequin provides a command to launch Harlequin using Django’s database configuration, like:
./manage.py harlequin
Keep Reading at harlequin.sh
Visit harlequin.sh for an overview of features and full documentation, starting with a guided walkthrough of how to edit and execute queries, use the data catalog, export data, and more.
Getting Help
To view all command-line options for Harlequin and all installed adapters, after installation, simply type:
harlequin --help
To view a subset of these docs (and a link back here) from within the app, press F1.
See the Troubleshooting guide for help with key bindings, appearance issues, copy-paste, etc.
GitHub Discussions are a good place to ask questions, request features, and say hello.
GitHub Issues are the best place to report bugs.
Sponsoring Harlequin
Please consider sponsoring Harlequin's author, so he can continue to dedicate time to Harlequin.
Contributing
Thanks for your interest in Harlequin! Harlequin is primarily maintained by Ted Conbeer, but he welcomes all contributions!
Please see CONTRIBUTING.md for more information.
1 maintainer
Metadata
1 maintainer
Release files for harlequin 2.14.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| harlequin-2.14.0.tar.gz | 301.9 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| harlequin-2.14.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 630.0 kB
Release files / harlequin-2.14.0.tar.gz
| Download URL | harlequin-2.14.0.tar.gz |
|---|---|
| Size | 301.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
623e085b700bd2486778751968615444f4b908a2081efad7b3bc0bdb34cc5be6
|
|
BLAKE2b-256 checksum How to use checksums |
116259e4f4fe3a98b62e1db9f91b5da47e79feac4a6be7cb848dd8db6e7ac67e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 14, 2026.
Transparency logRelease files / harlequin-2.14.0-py3-none-any.whl
| Download URL | harlequin-2.14.0-py3-none-any.whl |
|---|---|
| Size | 328.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
cd5f25e6100e3d9110bc4a5ea629dadedb611e6e662ed8ed2379e04939c6fbf9
|
|
BLAKE2b-256 checksum How to use checksums |
464c8a1c19eecbf4b6435c5ea60303eecae5b7932e794692d610f9aea1ca1a04
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 14, 2026.
Transparency log
