# Harlequin — The SQL IDE for Your Terminal

> A terminal-based SQL IDE with autocomplete, syntax highlighting, and a results viewer for DuckDB, SQLite, PostgreSQL, and more.

## Install

Save as a script file and run:

# Harlequin — The SQL IDE for Your Terminal

## Quick Use
```bash
pip install harlequin
# Open with DuckDB (default)
harlequin mydata.duckdb
# Open with SQLite
pip install harlequin-sqlite
harlequin -a sqlite mydb.sqlite
# Open with PostgreSQL
pip install harlequin-postgres
harlequin -a postgres "postgres://user:pass@localhost/db"
```

## 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

---
Source: https://tokrepo.com/en/workflows/asset-a5ce4d7c
Author: Script Depot