Harlequin: a SQL IDE that runs in your terminal

A Python-based SQL IDE for the terminal

Harlequin is a SQL IDE designed for terminal-first users who prefer command-line workflows. It provides an interactive environment for writing and executing SQL queries, exploring database schemas, and viewing results. The application is written in Python and built on the Textual TUI framework (version 8.2.8), which renders a rich, responsive user interface in the terminal with no external dependencies. Harlequin defaults to using DuckDB, an in-process analytical database that requires no setup; you can also use SQLite. Additional databases like Postgres, MySQL, MariaDB, Snowflake, Redshift, and others are supported via installable adapter packages. The pyproject.toml marks Harlequin as Development Status 4 (Beta), with version 2.15.0 released on 2026-09-16. The source code runs on Python 3.10 through 3.14. Recent commits arrived on 2026-09-29, indicating active development. Harlequin is MIT licensed. The repository includes CLAUDE.md (Claude integration instructions), AGENTS.md (agent use cases), a CONTRIBUTING.md guide for developers, comprehensive tests in the tests/ directory, and documentation in the docs/ folder covering getting started, adapters, configuration, themes, keymaps, and file browsing.

Installing Harlequin with uv or pip

Harlequin requires Python 3.10 or above. The README recommends installing using uv, a modern Python package manager. First, install uv from a POSIX shell:

curl -LsSf https://astral.sh/uv/install.sh | sh

Or from Windows Powershell:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Then install Harlequin into an isolated tool environment:

uv tool install harlequin

This adds it to your PATH automatically. Alternatively, install with pip, pipx, poetry, or any Python package installer:

pip install harlequin

A Homebrew formula is also available, though community-maintained and larger due to included adapter packages:

brew install harlequin

Start Harlequin with DuckDB (the default in-process database):

harlequin

This opens an in-memory session ready for queries. For SQLite:

harlequin --adapter sqlite

Open specific database files:

harlequin -a sqlite "path/to/sqlite.db" "another_sqlite.db"
harlequin "path/to/duck.db"   # for DuckDB

Run `harlequin --help` to see all options, which include theme selection, keymap customization, and file browser display. The repository includes examples of .harlequin.toml configuration files to demonstrate setup patterns and best practices. Testing is comprehensive: run `make check` to format code, lint with ruff, type-check with mypy, and test with pytest. The test suite marks online tests to skip them by default (run `pytest -m online` to include them in test runs). The library supports profiling with pyinstrument to measure performance bottlenecks in queries and rendering.

Database adapters and the plugin architecture

Harlequin ships with DuckDB (full in-process database) and SQLite (via built-in adapter). Other databases are accessed via installable adapter packages distributed as independent Python packages. The README mentions adapters for Postgres, MySQL, MariaDB, Snowflake, Redshift, BigQuery, and S3. These can be installed as extras via uv. For a single adapter:

uv tool install 'harlequin[postgres]'

You can install multiple extras:

uv tool install 'harlequin[postgres,mysql,s3]'

Other adapters can be installed as independent packages and are auto-discovered by Harlequin. This plugin architecture lets third-party developers extend Harlequin without modifying core code. The README directs users to harlequin.sh/docs/adapters for the complete list of maintained and community adapters. Each adapter can declare its own connection options and CLI flags, which appear in `harlequin --help` when that adapter is installed. When you have multiple adapters installed, Harlequin detects which one to use based on the connection string or the --adapter flag.

Configuration via profiles and environment variables

Harlequin supports configuration files that define profiles for different database connections and settings, documented in the config-file/ documentation directory. Profiles can set themes (dozens available for customization), customize keybindings (docs/keymaps/), control file browser visibility (docs/files/), and configure locale for number formatting. Configuration values can reference environment variables, allowing shared config files to keep credentials out of version control. The syntax is: `password = "${MYPASSWORD}"` or `${MYHOST:-localhost}` to supply a default. Values an adapter marks as secrets (like passwords) are masked in Harlequin's output, preventing accidental exposure in logs or terminal history. Harlequin includes a read-only mode (--read-only) that connects to the database in a mode where the database engine refuses write operations, and a timeout option (--timeout 30) to cancel queries taking longer than specified seconds. Both refuse to start if the adapter cannot enforce them, preventing silent failures. A companion tool, hsql, reads the same config files and can validate config with `hsql --config validate` and show schema with `hsql --config schema`.

Headless query execution with hsql for agents

Harlequin includes hsql, a companion command-line tool for non-interactive (headless) use, packaged with Harlequin and documented in docs/getting-started/hsql. hsql uses the same adapters and config files as Harlequin but is optimized for scripts and agents. Execute queries and get results in plain text format suitable for scripting, piping, or parsing:

hsql -P dev -c "select * from users"

Results are tab-separated text suitable for parsing or piping to other tools. hsql can explore database schemas without writing SQL: the `--catalog` flag with `--path` lists relations in a schema, no SQL queries required:

hsql --catalog --path mydb.analytics

Add a path to list columns:

hsql --catalog --path mydb.analytics.orders

The `--catalog-search` option searches for matching columns or relations across all levels. The `--read-only` and `--timeout` flags let you bound what an agent can do; both refuse to start if the adapter cannot enforce them, preventing silent failures. Configuration profiles apply to hsql as well, so a shared config file works for both Harlequin and hsql. This makes hsql ideal for automated data pipelines, CI/CD scripts, and agent-driven data exploration without requiring manual query writing or setup.

Django integration and development practices

For Django projects, the [django-harlequin](https://pypi.org/project/django-harlequin/) package (separate installation) provides a management command that launches Harlequin using Django's database configuration:

./manage.py harlequin

This allows Django developers to query their application database without manually creating connection strings. The repository demonstrates professional development practices. It uses uv for dependency management, pytest for testing with markers for online tests, mypy for type checking, and Textual's development server for interactive testing. The Makefile provides multiple targets: `make check` runs formatters and tests, `make lint` runs type checking, `make serve` launches the dev server, and `make keys` shows keybindings. The pyproject.toml declares development dependencies for linting (ruff), type checking (mypy), testing (pytest, chai, mocha), and documentation. Profiling targets measure buffer and query performance. The presence of comprehensive test groups, separate Python 3.12 tests, and profiling scripts indicates a mature, optimized development workflow.

Performance, themes, and result rendering

Harlequin renders result sets using textual-fastdatatable (0.19.3), a high-performance table widget optimized for large result sets in the terminal. This contrasts with naive rendering, which can be slow for thousands of rows. The library also uses textual-textarea (0.18.4) for the SQL editor with syntax highlighting. The Makefile includes profiling targets to measure buffer and query performance with pyinstrument, showing attention to optimization. Harlequin's keybindings and themes are customizable via configuration files. Run `harlequin --keys` to display the current keymap. The pyproject.toml declares support for Python 3.10 through 3.14. Dependencies are pinned to specific versions: Textual (8.2.8), textual-fastdatatable (0.19.3), textual-textarea (0.18.4), click (8.5.0), rich-click (1.9.9), tree-sitter (>=0.25,<0.27), tree-sitter-sql (>=0.3.11,<0.4), and DuckDB (1.1.1 on Python < 3.14). This version pinning eases deployment and reproducibility across environments.

Editorial conclusion

Adopt Harlequin if you write SQL regularly and prefer a terminal-first workflow, or if you work with DuckDB or SQLite and want an interactive query environment without leaving the shell. It suits data analysts, engineers, and developers who work in the terminal. Use hsql in scripts and agent automation. Skip Harlequin if you need a GUI with graphical database exploration, collaborative editing, or if you work only with cloud data warehouses that lack adapter support. To verify compatibility, install Harlequin with `uv tool install harlequin`, run it with no arguments (starts an in-memory DuckDB session), and query a sample dataset. Press `?` inside Harlequin to see the built-in help. The documentation site at harlequin.sh provides full getting started guides, adapter setup, and configuration examples.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. tconbeer/harlequin on GitHub