Hoja de Referencia de Harlequin - IDE SQL de Terminal

Hoja de Referencia de Harlequin - IDE SQL de Terminal

Un IDE SQL completo que se ejecuta completamente en tu terminal. Incluye resaltado de sintaxis, autocompletado, una barra lateral de catálogo de datos, múltiples adaptadores de base de datos y exportación de resultados — no se necesita GUI.

Instalación

Método	Comando
uv (Recomendado)	uv tool install harlequin
pip	pip install harlequin
pipx	pipx install harlequin
Homebrew	brew install harlequin
Poetry	poetry add harlequin

Instalación con Adaptadores de Base de Datos

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

Requiere: Python 3.9+

Lanzar Harlequin

Comando	Descripción
harlequin	Abrir con base de datos DuckDB en memoria
harlequin mydb.duckdb	Abrir un archivo de base de datos DuckDB
harlequin -a sqlite mydb.db	Abrir una base de datos SQLite
harlequin -a sqlite	Abrir base de datos SQLite en memoria
harlequin -a postgres -h localhost -p 5432 -U user -d mydb	Conectar a PostgreSQL
harlequin -a mysql -h localhost -u root mydb	Conectar a MySQL
harlequin --theme monokai	Usar un tema de color específico
harlequin --locale en_US	Establecer configuración regional de formato de números
harlequin --help	Mostrar todas las opciones de CLI

Atajos de Teclado en la Aplicación

Editor de Consultas

Tecla	Descripción
Ctrl+Enter	Ejecutar consulta actual
Ctrl+j	Ejecutar consulta actual (alternativo)
Ctrl+o	Abrir un archivo SQL
Ctrl+s	Guardar consulta actual a archivo
Ctrl+n	Nueva pestaña de consulta
Ctrl+w	Cerrar pestaña de consulta actual
Ctrl+k	Cambiar a siguiente pestaña de consulta
Tab	Aceptar sugerencia de autocompletado
Escape	Descartar menú de autocompletado
F1	Mostrar ayuda / documentación contextual

Panel de Resultados

Tecla	Descripción
Ctrl+r	Cambiar foco a panel de resultados
Ctrl+e	Cambiar foco a editor de consultas
Teclas de flecha	Navegar tabla de resultados
Ctrl+c	Copiar celda(s) seleccionada(s)

General

Tecla	Descripción
Ctrl+q	Salir de Harlequin
Ctrl+b	Alternar barra lateral de catálogo de datos
F1	Ayuda

Características Específicas de DuckDB

DuckDB es el adaptador predeterminado y soporta características poderosas:

-- 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');

Archivo de Configuración

Crear un archivo de configuración para guardar perfiles de conexión usados frecuentemente:

Configuración de Perfiles

# ~/.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"]

Usar perfiles con:

harlequin --profile local-pg

Adaptadores Disponibles

Adaptador	Extra de Instalación	Ejemplo de Conexión
DuckDB	(integrado)	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 en almacenamiento en la nube
ODBC	odbc	Conexiones ODBC genéricas
Trino	trino	Clústeres Trino/Presto
BigQuery	bigquery	Google BigQuery
Cassandra	cassandra	Apache Cassandra
ClickHouse	clickhouse	Bases de datos ClickHouse
MotherDuck	(vía DuckDB)	DuckDB en la nube

Flujos de Trabajo Comunes

# 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');

Integración con Django

# Install django-harlequin
pip install django-harlequin

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

Solución de Problemas

Problema	Solución
Adaptador no encontrado	Instalar con extras: uv tool install 'harlequin[postgres]'
Conexión rechazada	Verificar host, puerto y que el servidor de base de datos esté ejecutándose
Problemas de visualización	Probar un terminal diferente (Kitty, WezTerm, iTerm2 recomendados)
Lento en tablas grandes	Usar LIMIT en consultas; evitar SELECT * en tablas enormes
Falta autocompletado	Asegurar que estás conectado a una base de datos con esquema

Comparación con Otras Herramientas SQL

Característica	Harlequin	DBeaver	pgcli	usql
Se ejecuta en terminal	Sí	No (GUI)	Sí	Sí
Multi-base de datos	Sí	Sí	Solo Postgres	Sí
Autocompletado	Sí	Sí	Sí	No
Tabla de resultados visual	Sí	Sí	Básico	Básico
Consultas de archivos (CSV, Parquet)	Sí (DuckDB)	Limitado	No	No
Perfiles de configuración	Sí	Sí	Sí	No

Recursos

• Official Documentation
• GitHub Repository
• Adapter Directory