Harlequin - Folha de Referência da IDE SQL de Terminal

Uma IDE SQL completa que roda inteiramente em seu terminal. Apresenta destaque de sintaxe, autocompletar, barra lateral de catálogo de dados, múltiplos adaptadores de banco de dados e exportação de resultados — sem necessidade de GUI.

Instalação

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`

Instalando com Adaptadores de Banco de Dados

# DuckDB (integrado, sem instalação extra necessária)
uv tool install harlequin

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

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

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

# Múltiplos adaptadores de uma vez
uv tool install 'harlequin[postgres,mysql,sqlite,s3]'

Requisitos: Python 3.9+

Iniciando o Harlequin

Comando	Descrição
`harlequin`	Abrir com banco de dados DuckDB em memória
`harlequin mydb.duckdb`	Abrir um arquivo de banco de dados DuckDB
`harlequin -a sqlite mydb.db`	Abrir um banco de dados SQLite
`harlequin -a sqlite`	Abrir banco de dados SQLite em memória
`harlequin -a postgres -h localhost -p 5432 -U user -d mydb`	Conectar ao PostgreSQL
`harlequin -a mysql -h localhost -u root mydb`	Conectar ao MySQL
`harlequin --theme monokai`	Usar um tema de cores específico
`harlequin --locale en_US`	Definir localização de formatação de números
`harlequin --help`	Mostrar todas as opções CLI

Atalhos de Teclado no Aplicativo

Editor de Consultas

Tecla	Descrição
`Ctrl+Enter`	Executar consulta atual
`Ctrl+j`	Executar consulta atual (alternativa)
`Ctrl+o`	Abrir um arquivo SQL
`Ctrl+s`	Salvar consulta atual em arquivo
`Ctrl+n`	Nova aba de consulta
`Ctrl+w`	Fechar aba de consulta atual
`Ctrl+k`	Mudar para próxima aba de consulta
`Tab`	Aceitar sugestão de autocompletar
`Escape`	Dispensar menu de autocompletar
`F1`	Mostrar ajuda / documentação contextual

Painel de Resultados

Tecla	Descrição
`Ctrl+r`	Mudar foco para painel de resultados
`Ctrl+e`	Mudar foco para editor de consultas
Setas direcionais	Navegar tabela de resultados
`Ctrl+c`	Copiar célula(s) selecionada(s)

Geral

Tecla	Descrição
`Ctrl+q`	Sair do Harlequin
`Ctrl+b`	Alternar barra lateral de catálogo de dados
`F1`	Ajuda

Recursos Específicos do DuckDB

DuckDB é o adaptador padrão e suporta recursos poderosos:

-- Ler arquivos CSV diretamente
SELECT * FROM read_csv_auto('data.csv');

-- Ler arquivos Parquet
SELECT * FROM read_parquet('data.parquet');

-- Ler arquivos JSON
SELECT * FROM read_json_auto('data.json');

-- Consultar arquivos remotos
SELECT * FROM read_csv_auto('https://example.com/data.csv');

-- Consultar arquivos S3 (com adaptador s3)
SELECT * FROM read_parquet('s3://bucket/data.parquet');

-- Agregar dados de múltiplos arquivos
SELECT * FROM read_csv_auto('logs/*.csv');

Arquivo de Configuração

Crie um arquivo de configuração para salvar perfis de conexão frequentemente usados:

Configuração de Perfil

# ~/.config/harlequin/config.toml
# (ou use flag --config para especificar caminho)

[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 perfis com:

harlequin --profile local-pg

Adaptadores Disponíveis

Adaptador	Instalação Extra	Exemplo de Conexão
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 em armazenamento na nuvem
ODBC	`odbc`	Conexões ODBC genéricas
Trino	`trino`	Clusters Trino/Presto
BigQuery	`bigquery`	Google BigQuery
Cassandra	`cassandra`	Apache Cassandra
ClickHouse	`clickhouse`	Bancos de dados ClickHouse
MotherDuck	(via DuckDB)	DuckDB na nuvem

Fluxos de Trabalho Comuns

# Exploração rápida de dados — abrir CSV como banco de dados
harlequin
# Então no editor de consultas: SELECT * FROM read_csv_auto('data.csv') LIMIT 100;

# Explorar um banco de dados SQLite (ex: DB de app mobile)
harlequin -a sqlite app.db

# Conectar ao Postgres local para desenvolvimento
harlequin -a postgres -h localhost -p 5432 -U dev -d myapp_dev

# Analisar arquivos Parquet sem carregar em um banco de dados
harlequin
# Então: SELECT * FROM read_parquet('output/*.parquet');

Integração com Django

# Instalar django-harlequin
pip install django-harlequin

# Iniciar Harlequin conectado ao seu DB Django
./manage.py harlequin

Solução de Problemas

Problema	Solução
Adaptador não encontrado	Instalar com extras: `uv tool install 'harlequin[postgres]'`
Conexão recusada	Verificar host, porta e se o servidor de banco de dados está rodando
Problemas de exibição	Tente um terminal diferente (Kitty, WezTerm, iTerm2 recomendados)
Lento em tabelas grandes	Use `LIMIT` em consultas; evite `SELECT *` em tabelas enormes
Autocompletar faltando	Certifique-se de estar conectado a um banco de dados com esquema

Comparação com Outras Ferramentas SQL

Recurso	Harlequin	DBeaver	pgcli	usql
Roda em terminal	Sim	Não (GUI)	Sim	Sim
Multi-banco de dados	Sim	Sim	Apenas Postgres	Sim
Autocompletar	Sim	Sim	Sim	Não
Tabela de resultados visual	Sim	Sim	Básica	Básica
Consultas de arquivo (CSV, Parquet)	Sim (DuckDB)	Limitado	Não	Não
Perfis de configuração	Sim	Sim	Sim	Não