Harlequin — The SQL IDE for Your Terminal

Introduction

Harlequin is a terminal-based SQL IDE that brings the features of graphical database tools into the command line. It provides a full editing experience with autocomplete, syntax highlighting, multiple query tabs, and a scrollable results table, all running in a TUI powered by Textual. It was built for developers who prefer working in the terminal but need more than a basic CLI client.

What Harlequin Does

• Provides a full SQL editor in the terminal with autocomplete and syntax highlighting
• Displays query results in a scrollable, sortable table with column resizing
• Supports multiple database backends via an adapter plugin system
• Shows a data catalog sidebar with schemas, tables, and columns
• Allows exporting query results to CSV, JSON, and Parquet files

Architecture Overview

Harlequin is a Python application built on the Textual TUI framework. It uses a plugin-based adapter system where each database backend (DuckDB, SQLite, PostgreSQL, MySQL) is a separate installable package. The editor widget provides syntax-aware editing, and the results viewer uses efficient lazy loading to handle large result sets without consuming excessive memory.

Self-Hosting & Configuration

• Install the core package and any adapter plugins via pip or pipx
• Configure default adapter and connection settings via a TOML profile file
• Customize keybindings and editor theme through the configuration file
• Pass connection strings directly on the command line for quick sessions
• Use the --init flag to execute SQL scripts on startup for environment setup

Key Features

• Intelligent autocomplete suggests table names, columns, and SQL keywords
• Multiple query tabs let you work on several queries simultaneously
• Data catalog sidebar displays the full schema tree for connected databases
• Results can be exported to CSV, JSON, or Parquet without leaving the TUI
• Plugin system supports DuckDB, SQLite, PostgreSQL, MySQL, and community adapters

Comparison with Similar Tools

• pgcli/mycli — pgcli is a readline-based CLI; Harlequin is a full TUI IDE with a results viewer
• DBeaver — DBeaver is a graphical desktop IDE; Harlequin provides similar features in the terminal
• usql — usql is a universal CLI client; Harlequin adds an IDE experience with tabs and autocomplete
• DataGrip — DataGrip is a commercial JetBrains product; Harlequin is free and terminal-native
• litecli — litecli targets SQLite only; Harlequin supports multiple backends via adapters

FAQ

Q: Which databases does Harlequin support? A: DuckDB (built-in), SQLite, PostgreSQL, and MySQL via adapter plugins. Community adapters add support for additional databases.

Q: Can I use Harlequin over SSH? A: Yes. Since it runs entirely in the terminal, it works over SSH sessions with no port forwarding or GUI forwarding required.

Q: Does Harlequin support large result sets? A: Yes. The results viewer uses lazy loading so it can display millions of rows without loading them all into memory at once.

Q: Can I customize the color theme? A: Yes. Harlequin supports Pygments themes for syntax highlighting and allows custom color configuration in its TOML config file.

Sources

• https://github.com/tconbeer/harlequin
• https://harlequin.sh