Harlequin puts a SQL editor in the terminal and pushes the safety rules down into the adapter
The SQL IDE for Your Terminal.
At a glance
- What is it?
- A Python and Textual SQL IDE that ships DuckDB and SQLite in the box, reaches every other database through separately installed adapter packages, and pairs with hsql for headless runs. The interesting parts are the Python floor, the silent creation of database files, and the read-only mode that fails loudly when an adapter cannot back it.
- Who is it for?
- Harlequin fits a developer who wants to open a local DuckDB or SQLite file from a shell without a server or a browser tab, and who is willing to treat adapter extras as part of the install. Check the Python floor against your interpreter before anything else, because the README text and the packaging metadata disagree about 3.9.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 3 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- tconbeer/harlequin6,522 ★ · +107
| Repository | 2026-09-23 | 2026-11-15 |
|---|---|---|
| tconbeer/harlequin | 6.4k | 6.5k |
107 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
Two adapters ship in the box and everything else is a separate install
Harlequin bundles exactly two database adapters. The DuckDB adapter is the default and ships the full DuckDB database in process, so a bare `harlequin` with no arguments opens an in memory session with nothing to set up. The SQLite3 adapter also ships, and you select it with `--adapter sqlite` rather than by naming a package.
Everything else is a plug-in distributed as its own Python package that has to land in the same environment as Harlequin itself. Extras are the short path to those, which is why Postgres, MySQL, and S3 are decided at install time rather than at run time.
uv tool install harlequin
harlequin --help
harlequinThat split is the first thing to understand about the layout: two databases cost nothing and work immediately, and everything past them is a packaging decision you make before the program starts.
Connection strings do double duty as file paths
The command line takes a list of connection strings with no flag in front of them, which is how one invocation ends up with two databases at once. `harlequin "path/to/duck.db" "another_duck.db"` treats each argument as a path, and Harlequin creates the DuckDB databases when they are not already there.
The silence on that create step matters. A mistyped relative path becomes a new empty database file rather than an error, and nothing in the argument list records what you meant to open. SQLite files are opened the same way, by passing their paths once the adapter is selected.
harlequin --adapter sqlite
harlequin -a sqlite "path/to/sqlite.db" "another_sqlite.db"The `-a` alias saves typing, at the cost of a flag you also have to understand when you read a shell history line back to yourself.
hsql shares the adapters and the config files but not the screen
hsql is Harlequin's companion CLI. It ships inside the Harlequin install, uses the same adapters, reads the same config files, and is built for headless use by agents and in automations.
$ hsql -P dev -c "select * from users"
id | name
----+---------
1 | Ted
2 | Patrick
(2 rows)You can also explore a catalog without writing any SQL: `hsql --catalog --path mydb.analytics` lists a schema's relations, appending `.orders` lists that table's columns, and `hsql --catalog-search customer_id` searches every level at once. What hsql does not give you is the editor, the query buffer, or the results grid. It is a way to ask a database a question from a script, not a second front end.
Read-only and timeout are refusals rather than warnings
The two guardrails that matter for an unattended run are enforced instead of advisory. `--read-only` connects in a mode the database refuses writes in, rather than relying on Harlequin to filter statements before they leave the buffer. `hsql --timeout 30` cancels a run that takes longer than that.
Both are also profile keys, so a profile can pin them instead of a command line. Both refuse to start if the adapter cannot enforce them. That is the useful part: a missing capability shows up as a startup failure you can diagnose, not as a silent downgrade to a weaker promise. Harlequin takes `--read-only` too, for opening a production database without worrying about a stray statement.
The Python floor in pyproject.toml disagrees with the README text
The declared floor and the documented floor do not match. `requires-python = ">=3.10"` in pyproject.toml is what the installer enforces, and the classifiers run from 3.10 through 3.14. The README text instead says to install Python 3.9 or above before using pip, so a 3.9 user can follow the documentation and still fail at install.
The pins are version aware around the same boundary. DuckDB is held at `>=1.1.1` below Python 3.14 and forced up to `>=1.4.2` at 3.14 and above, and tomli appears only for interpreters before 3.11.
On the wider dependency question, textual, click, textual-textarea, and textual-fastdatatable are all pinned to exact patch releases, while tree-sitter, tree-sitter-sql, platformdirs, msgspec, and pyperclip take ranges. The packaging metadata does not allow installing on 3.9.
A shared profile holds variable names instead of credentials
A profile is the unit you can hand to a teammate. String values resolve environment variables, so `password = "${MYPASSWORD}"` keeps the credential out of the file and `${MYHOST:-localhost}` supplies a default when the variable is unset. Values an adapter declares as secrets are masked wherever Harlequin prints them, and hsql reads the same files, so one profile answers to both front ends. `hsql --config show`, `--config validate`, and `--config schema` report on those files without opening the editor.
Profiles are also where the theme, the key bindings, whether remote and local files are shown, and the locale used to format numbers get set.
The Homebrew formula bundles three adapters and skips isolation
The install method decides how much gets tested and how much gets bundled. `uv tool install harlequin` puts the program in an isolated environment and adds it to your PATH, which is the route the project points at first. `pip install harlequin` works on any supported Python but hands you responsibility for the surrounding environment.
`brew install harlequin` is a different bargain. The formula is maintained by the community and described as not as rigorously tested as the Python installations, and it includes the Postgres, MySQL/MariaDB, and ODBC adapter packages along with their dependencies. That is convenient, and it increases the application size.
What the formula does not give you is adapter isolation, so the extra drivers ride along whether or not you ever point them at a database. Extras keep that choice explicit:
uv tool install 'harlequin[postgres]'
uv tool install 'harlequin[postgres,mysql,s3]'make check leaves out every test that needs a network
The checked in Makefile shows how the project examines itself, and its most revealing line is a marker rather than a command. `TEST_MARKERS := not online` carries a comment saying the online tests need a network connection and secrets, kept as a marker expression because a second `-m` would silently override the first.
`make check` syncs the test and static groups, runs ruff format, ruff check with fix, and pytest under that marker, repeats pytest on Python 3.12 limited to `py12`, then finishes with mypy and lint-imports. Separate targets exist for a cold start script, for staging the artifacts a release publishes to harlequin.sh, and for launching the editor against a local file under the dev profile.
Django users get their own entry point through a separate package: `./manage.py harlequin`.
Editorial conclusion
Harlequin fits a developer who wants to open a local DuckDB or SQLite file from a shell without a server or a browser tab, and who is willing to treat adapter extras as part of the install. Check the Python floor against your interpreter before anything else, because the README text and the packaging metadata disagree about 3.9. Decide early whether you need hsql rather than the editor, since the guardrails that matter for automation exist only where an adapter enforces them.
Frequently asked questions
Do I need a database server running before I can try Harlequin?
No. The DuckDB adapter is the default and ships the full DuckDB database in process, so running `harlequin` with no arguments opens an in memory session. A bundled SQLite3 adapter is reached with `--adapter sqlite`.
Which Python versions does Harlequin actually support?
pyproject.toml sets `requires-python = ">=3.10"` and the classifiers list 3.10 through 3.14. The README text mentions Python 3.9 or above, which the packaging metadata does not honor.
How do I connect to Postgres or S3 with Harlequin?
Adapters are separate Python packages that must be installed into the same environment as Harlequin. Extras do it at install time, for example `uv tool install 'harlequin[postgres,mysql,s3]'`.
Do I have to install hsql separately to script queries?
No, hsql is packaged with Harlequin. It uses the same adapters and config files, and accepts options such as `-P` for a profile, `-c` for a command, `--catalog`, `--read-only`, and `--timeout`.
Can I keep database passwords out of a Harlequin config file?
A profile's string values can name environment variables, such as `password = "${MYPASSWORD}"` or `${MYHOST:-localhost}` for a default. Values an adapter declares as secrets are masked wherever Harlequin prints them.
What happens if I pass a database path that does not exist yet?
For DuckDB, Harlequin creates the databases if they do not exist, so a bad relative path becomes a new empty file rather than an error. SQLite files are opened the same way by passing their paths as connection strings.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/tconbeer-harlequin)Star history chart for your README
[](https://hysenlabs.com/projects/tconbeer-harlequin)Was this useful?