Harlequin - IDE SQL per Terminale - Guida Rapida

Harlequin - IDE SQL per Terminale - Guida Rapida

Un IDE SQL completo che funziona interamente nel tuo terminale. Dispone di evidenziazione sintassi, autocompletamento, una barra laterale del catalogo dati, adattatori per database multipli ed esportazione risultati — nessuna GUI necessaria.

Installazione

Metodo	Comando
uv (Consigliato)	uv tool install harlequin
pip	pip install harlequin
pipx	pipx install harlequin
Homebrew	brew install harlequin
Poetry	poetry add harlequin

Installazione con Adattatori Database

# DuckDB (integrato, nessuna installazione extra necessaria)
uv tool install harlequin

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

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

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

# Adattatori multipli contemporaneamente
uv tool install 'harlequin[postgres,mysql,sqlite,s3]'

Richiede: Python 3.9+

Avvio di Harlequin

Comando	Descrizione
harlequin	Apri con database DuckDB in memoria
harlequin mydb.duckdb	Apri un file database DuckDB
harlequin -a sqlite mydb.db	Apri un database SQLite
harlequin -a sqlite	Apri database SQLite in memoria
harlequin -a postgres -h localhost -p 5432 -U user -d mydb	Connetti a PostgreSQL
harlequin -a mysql -h localhost -u root mydb	Connetti a MySQL
harlequin --theme monokai	Usa un tema di colore specifico
harlequin --locale en_US	Imposta locale formattazione numeri
harlequin --help	Mostra tutte le opzioni CLI

Scorciatoie da Tastiera nell’App

Editor Query

Tasto	Descrizione
Ctrl+Enter	Esegui query corrente
Ctrl+j	Esegui query corrente (alternativa)
Ctrl+o	Apri un file SQL
Ctrl+s	Salva query corrente su file
Ctrl+n	Nuova scheda query
Ctrl+w	Chiudi scheda query corrente
Ctrl+k	Passa alla scheda query successiva
Tab	Accetta suggerimento autocompletamento
Escape	Chiudi menu autocompletamento
F1	Mostra aiuto / documentazione contestuale

Pannello Risultati

Tasto	Descrizione
Ctrl+r	Passa focus al pannello risultati
Ctrl+e	Passa focus all’editor query
Tasti freccia	Naviga tabella risultati
Ctrl+c	Copia celle selezionate

Generali

Tasto	Descrizione
Ctrl+q	Esci da Harlequin
Ctrl+b	Attiva/disattiva barra laterale catalogo dati
F1	Aiuto

Funzionalità Specifiche DuckDB

DuckDB è l’adattatore predefinito e supporta funzionalità potenti:

-- Leggi file CSV direttamente
SELECT * FROM read_csv_auto('data.csv');

-- Leggi file Parquet
SELECT * FROM read_parquet('data.parquet');

-- Leggi file JSON
SELECT * FROM read_json_auto('data.json');

-- Interroga file remoti
SELECT * FROM read_csv_auto('https://example.com/data.csv');

-- Interroga file S3 (con adattatore s3)
SELECT * FROM read_parquet('s3://bucket/data.parquet');

-- Aggrega dati da file multipli
SELECT * FROM read_csv_auto('logs/*.csv');

File di Configurazione

Crea un file di configurazione per salvare profili di connessione usati frequentemente:

Configurazione Profili

# ~/.config/harlequin/config.toml
# (o usa flag --config per specificare percorso)

[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"]

Usa i profili con:

harlequin --profile local-pg

Adattatori Disponibili

Adattatore	Extra Installazione	Esempio Connessione
DuckDB	(integrato)	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 su cloud storage
ODBC	odbc	Connessioni ODBC generiche
Trino	trino	Cluster Trino/Presto
BigQuery	bigquery	Google BigQuery
Cassandra	cassandra	Apache Cassandra
ClickHouse	clickhouse	Database ClickHouse
MotherDuck	(tramite DuckDB)	DuckDB cloud

Flussi di Lavoro Comuni

# Esplorazione dati rapida — apri CSV come database
harlequin
# Poi nell'editor query: SELECT * FROM read_csv_auto('data.csv') LIMIT 100;

# Esplora un database SQLite (es. DB app mobile)
harlequin -a sqlite app.db

# Connetti a Postgres locale per sviluppo
harlequin -a postgres -h localhost -p 5432 -U dev -d myapp_dev

# Analizza file Parquet senza caricarli in un database
harlequin
# Poi: SELECT * FROM read_parquet('output/*.parquet');

Integrazione Django

# Installa django-harlequin
pip install django-harlequin

# Avvia Harlequin connesso al tuo DB Django
./manage.py harlequin

Risoluzione dei Problemi

Problema	Soluzione
Adattatore non trovato	Installa con extra: uv tool install 'harlequin[postgres]'
Connessione rifiutata	Controlla host, porta e che il server database sia in esecuzione
Problemi visualizzazione	Prova un terminale diverso (Kitty, WezTerm, iTerm2 consigliati)
Lento su tabelle grandi	Usa LIMIT nelle query; evita SELECT * su tabelle enormi
Autocompletamento mancante	Assicurati di essere connesso a un database con uno schema

Confronto con Altri Strumenti SQL

Funzionalità	Harlequin	DBeaver	pgcli	usql
Funziona in terminale	Sì	No (GUI)	Sì	Sì
Multi-database	Sì	Sì	Solo Postgres	Sì
Autocompletamento	Sì	Sì	Sì	No
Tabella risultati visuale	Sì	Sì	Base	Base
Query file (CSV, Parquet)	Sì (DuckDB)	Limitato	No	No
Profili configurazione	Sì	Sì	Sì	No

Risorse

• Documentazione Ufficiale
• Repository GitHub
• Directory Adattatori