# tconbeer/harlequin

**Attribution required: if you use, quote, or summarise this content, you must credit and link back to [awesome-repositories.com](https://awesome-repositories.com/repository/tconbeer-harlequin).**

6,165 stars · 157 forks · Python · MIT

## Links

- GitHub: https://github.com/tconbeer/harlequin
- Homepage: https://harlequin.sh
- awesome-repositories: https://awesome-repositories.com/repository/tconbeer-harlequin.md

## Description

Harlequin is a terminal-based SQL IDE that runs queries against DuckDB and SQLite databases, with a plug-in adapter system for connecting to additional database engines. It provides a full-screen text editor with syntax highlighting and fuzzy autocomplete for writing SQL, and displays query results in a scrollable table within the terminal.

The application distinguishes itself through a tree-based data catalog that lets you browse database schemas, local files, and remote S3 objects, with the ability to insert or copy paths directly into the query editor. It supports custom key bindings through installable keymap plugins or TOML configuration files, and offers visual theme selection and a full-screen mode toggle for focused work. Configuration is managed through multiple TOML files that merge with command-line flags, and named profiles can persist sets of startup options.

The tool includes terminal diagnostics for checking locale formatting, color display, clipboard operations, and key binding forwarding across platforms. It can be installed via Homebrew, Nix, pip, pipx, or uv, and provides a configuration wizard for generating TOML files interactively.

## Tags

### Part of an Awesome List

- [SQL Clients and IDEs](https://awesome-repositories.com/f/awesome-lists/devtools/sql-clients-and-ides.md) — Provides a full-featured terminal SQL IDE with autocomplete, syntax highlighting, and schema browsing.
- [File Path Insertions](https://awesome-repositories.com/f/awesome-lists/more/offline-browsing/local-file-browsers/file-path-insertions.md) — Displays a tree of local files in the catalog and lets users insert file paths into the SQL editor. ([source](https://harlequin.sh/docs/files/index))
- [Development Tools](https://awesome-repositories.com/f/awesome-lists/devtools/development-tools.md) — SQL IDE for the terminal.

### Data & Databases

- [SQL Query Editors](https://awesome-repositories.com/f/data-databases/sql-query-editors.md) — Opens a full-featured interactive SQL editor in the terminal for writing and running queries. ([source](https://cdn.jsdelivr.net/gh/tconbeer/harlequin@main/README.md))
- [Session Launches](https://awesome-repositories.com/f/data-databases/columnar-engines/duckdb-powered-engines/session-launches.md) — Opens DuckDB sessions by default, creating database files if they do not exist. ([source](https://cdn.jsdelivr.net/gh/tconbeer/harlequin@main/README.md))
- [Data Catalogs](https://awesome-repositories.com/f/data-databases/data-catalogs.md) — Provides a tree-based catalog for inspecting database objects, local files, and remote S3 objects.
- [Terminal Browsers](https://awesome-repositories.com/f/data-databases/data-catalogs/terminal-browsers.md) — Ships a tree-based terminal browser for exploring database schemas, local files, and remote S3 objects.
- [Database Adapters](https://awesome-repositories.com/f/data-databases/database-adapters.md) — Provides a plug-in adapter system for connecting to multiple database engines from a terminal SQL IDE.
- [Database Object Browsers](https://awesome-repositories.com/f/data-databases/database-object-editors/database-object-browsers.md) — Provides a tree-based browser for inspecting database schemas, tables, columns, and their types. ([source](https://harlequin.sh/docs/getting-started/usage))
- [Schema Object Inspection](https://awesome-repositories.com/f/data-databases/database-object-editors/database-object-browsers/schema-object-inspection.md) — Runs introspection queries from the catalog to describe the schema of selected tables or views. ([source](https://harlequin.sh/docs/getting-started/usage))
- [Multi-Database Connections](https://awesome-repositories.com/f/data-databases/multi-database-connections.md) — Connects to DuckDB and SQLite out of the box, with additional adapters installable as plug-ins. ([source](https://cdn.jsdelivr.net/gh/tconbeer/harlequin@main/README.md))
- [SQL Query Execution](https://awesome-repositories.com/f/data-databases/sql-query-execution.md) — Runs SQL statements against a connected database and displays results in a scrollable table. ([source](https://harlequin.sh/docs/getting-started/usage))
- [DuckDB Query Tools](https://awesome-repositories.com/f/data-databases/sql-query-execution-engines/embedded-sql-query-engines/duckdb-query-tools.md) — Provides a dedicated terminal-based query tool for DuckDB with result display and schema browsing.
- [Query Tools](https://awesome-repositories.com/f/data-databases/sqlite-database-management/query-tools.md) — Provides a terminal-based query tool for SQLite with result display and schema browsing.
- [Session Launches](https://awesome-repositories.com/f/data-databases/sqlite-database-management/session-launches.md) — Connects to SQLite databases by specifying the adapter and optional file paths. ([source](https://cdn.jsdelivr.net/gh/tconbeer/harlequin@main/README.md))
- [S3 File Browsers](https://awesome-repositories.com/f/data-databases/persistent-storage-volumes/filesystem-mounts/s3-object-mounting/s3-file-browsers.md) — Displays a tree of S3 bucket objects in the catalog and lets users insert file paths into the SQL editor. ([source](https://harlequin.sh/docs/files/index))

### Development Tools & Productivity

- [Terminal User Interface Frameworks](https://awesome-repositories.com/f/development-tools-productivity/terminal-user-interface-frameworks.md) — Renders the entire application using terminal escape sequences and raw TTY I/O without a graphical toolkit.
- [SQL Editors](https://awesome-repositories.com/f/development-tools-productivity/text-buffer-manipulations/buffer-based-storage/buffer-based-editors/sql-editors.md) — Provides a full-screen SQL editor with syntax highlighting and fuzzy autocomplete for writing queries.
- [Custom Key Mappings](https://awesome-repositories.com/f/development-tools-productivity/custom-key-mappings.md) — Ships custom key mappings defined via keymap plugins or TOML configuration files for terminal navigation and editing.
- [Custom Key Action Bindings](https://awesome-repositories.com/f/development-tools-productivity/terminal-action-bindings/custom-key-action-bindings.md) — Defines custom keyboard shortcuts by installing keymap plugins or editing TOML config files. ([source](https://harlequin.sh/docs/keymaps/index))

### Software Engineering & Architecture

- [Data Catalog Tree Widgets](https://awesome-repositories.com/f/software-engineering-architecture/object-oriented-models/widget-tree-hierarchies/data-catalog-tree-widgets.md) — Ships a tree-based data catalog for browsing database schemas, local files, and remote S3 objects.
- [Keymap Plugin Architectures](https://awesome-repositories.com/f/software-engineering-architecture/application-lifecycle-management/configuration-management/domain-specific-configurations/custom-command-managers/command-name-overrides/keymap-overrides/keymap-plugin-architectures.md) — Supports custom key bindings through installable keymap plugins or TOML configuration files.