Harlequin - Terminal SQL IDE Cheatsheet

Harlequin - Terminal SQL IDE Cheatsheet

A full-featured SQL IDE that runs entirely in your terminal. Features syntax highlighting, autocomplete, a data catalog sidebar, multiple database adapters, and results export — no GUI needed.

Installation

Method	Command
uv (Recommended)	uv tool install harlequin
pip	pip install harlequin
pipx	pipx install harlequin
Homebrew	brew install harlequin
Poetry	poetry add harlequin

Installing with Database Adapters

# DuckDB (built-in, no extra install needed)
uv tool install harlequin

# SQLite adapter
uv tool install 'harlequin[sqlite]'

# PostgreSQL adapter
uv tool install 'harlequin[postgres]'

# MySQL adapter
uv tool install 'harlequin[mysql]'

# Multiple adapters at once
uv tool install 'harlequin[postgres,mysql,sqlite,s3]'

Requires: Python 3.9+

Launching Harlequin

Command	Description
harlequin	Open with in-memory DuckDB database
harlequin mydb.duckdb	Open a DuckDB database file
harlequin -a sqlite mydb.db	Open a SQLite database
harlequin -a sqlite	Open in-memory SQLite database
harlequin -a postgres -h localhost -p 5432 -U user -d mydb	Connect to PostgreSQL
harlequin -a mysql -h localhost -u root mydb	Connect to MySQL
harlequin --theme monokai	Use a specific color theme
harlequin --locale en_US	Set number formatting locale
harlequin --help	Show all CLI options

In-App Keybindings

Query Editor

Key	Description
Ctrl+Enter	Execute current query
Ctrl+j	Execute current query (alternative)
Ctrl+o	Open a SQL file
Ctrl+s	Save current query to file
Ctrl+n	New query tab
Ctrl+w	Close current query tab
Ctrl+k	Switch to next query tab
Tab	Accept autocomplete suggestion
Escape	Dismiss autocomplete menu
F1	Show help / contextual documentation

Results Panel

Key	Description
Ctrl+r	Switch focus to results panel
Ctrl+e	Switch focus to query editor
Arrow keys	Navigate results table
Ctrl+c	Copy selected cell(s)

General

Key	Description
Ctrl+q	Quit Harlequin
Ctrl+b	Toggle data catalog sidebar
F1	Help

DuckDB-Specific Features

DuckDB is the default adapter and supports powerful features:

-- Read CSV files directly
SELECT * FROM read_csv_auto('data.csv');

-- Read Parquet files
SELECT * FROM read_parquet('data.parquet');

-- Read JSON files
SELECT * FROM read_json_auto('data.json');

-- Query remote files
SELECT * FROM read_csv_auto('https://example.com/data.csv');

-- Query S3 files (with s3 adapter)
SELECT * FROM read_parquet('s3://bucket/data.parquet');

-- Aggregate data from multiple files
SELECT * FROM read_csv_auto('logs/*.csv');

Configuration File

Create a config file to save frequently-used connection profiles:

Profile Configuration

# ~/.config/harlequin/config.toml
# (or use --config flag to specify path)

[profiles.local-pg]
adapter = "postgres"
host = "localhost"
port = 5432
user = "myuser"
database = "mydb"

[profiles.prod-readonly]
adapter = "postgres"
host = "prod-db.example.com"
port = 5432
user = "readonly"
database = "production"
theme = "monokai"

[profiles.duckdb-analytics]
adapter = "duckdb"
conn_str = ["analytics.duckdb"]

Use profiles with:

harlequin --profile local-pg

Available Adapters

Adapter	Install Extra	Connection Example
DuckDB	(built-in)	harlequin data.duckdb
SQLite	sqlite	harlequin -a sqlite data.db
PostgreSQL	postgres	harlequin -a postgres -h host -U user -d db
MySQL	mysql	harlequin -a mysql -h host -u user db
S3 / GCS	s3	Parquet/CSV on cloud storage
ODBC	odbc	Generic ODBC connections
Trino	trino	Trino/Presto clusters
BigQuery	bigquery	Google BigQuery
Cassandra	cassandra	Apache Cassandra
ClickHouse	clickhouse	ClickHouse databases
MotherDuck	(via DuckDB)	Cloud DuckDB

Common Workflows

# Quick data exploration — open CSV as a database
harlequin
# Then in query editor: SELECT * FROM read_csv_auto('data.csv') LIMIT 100;

# Explore a SQLite database (e.g., a mobile app DB)
harlequin -a sqlite app.db

# Connect to local Postgres for development
harlequin -a postgres -h localhost -p 5432 -U dev -d myapp_dev

# Analyze Parquet files without loading into a database
harlequin
# Then: SELECT * FROM read_parquet('output/*.parquet');

Django Integration

# Install django-harlequin
pip install django-harlequin

# Launch Harlequin connected to your Django DB
./manage.py harlequin

Troubleshooting

Issue	Solution
Adapter not found	Install with extras: uv tool install 'harlequin[postgres]'
Connection refused	Check host, port, and that the database server is running
Display issues	Try a different terminal (Kitty, WezTerm, iTerm2 recommended)
Slow on large tables	Use LIMIT in queries; avoid SELECT * on huge tables
Missing autocomplete	Ensure you’re connected to a database with a schema

Comparison with Other SQL Tools

Feature	Harlequin	DBeaver	pgcli	usql
Runs in terminal	Yes	No (GUI)	Yes	Yes
Multi-database	Yes	Yes	Postgres only	Yes
Autocomplete	Yes	Yes	Yes	No
Visual results table	Yes	Yes	Basic	Basic
File queries (CSV, Parquet)	Yes (DuckDB)	Limited	No	No
Config profiles	Yes	Yes	Yes	No

Resources

• Official Documentation
• GitHub Repository
• Adapter Directory