Harlequin - 터미널 SQL IDE 치트시트

Harlequin - 터미널 SQL IDE 치트시트

터미널에서 완전히 실행되는 완전한 기능을 갖춘 SQL IDE. 구문 강조, 자동완성, 데이터 카탈로그 사이드바, 여러 데이터베이스 어댑터 및 결과 내보내기 — GUI 필요 없음.

설치

방법	명령어
uv (권장)	uv tool install harlequin
pip	pip install harlequin
pipx	pipx install harlequin
Homebrew	brew install harlequin
Poetry	poetry add harlequin

데이터베이스 어댑터와 함께 설치

# DuckDB (내장, 추가 설치 필요 없음)
uv tool install harlequin

# SQLite 어댑터
uv tool install 'harlequin[sqlite]'

# PostgreSQL 어댑터
uv tool install 'harlequin[postgres]'

# MySQL 어댑터
uv tool install 'harlequin[mysql]'

# 여러 어댑터를 한 번에
uv tool install 'harlequin[postgres,mysql,sqlite,s3]'

필수: Python 3.9+

Harlequin 실행

명령어	설명
harlequin	메모리 내 DuckDB 데이터베이스로 열기
harlequin mydb.duckdb	DuckDB 데이터베이스 파일 열기
harlequin -a sqlite mydb.db	SQLite 데이터베이스 열기
harlequin -a sqlite	메모리 내 SQLite 데이터베이스 열기
harlequin -a postgres -h localhost -p 5432 -U user -d mydb	PostgreSQL에 연결
harlequin -a mysql -h localhost -u root mydb	MySQL에 연결
harlequin --theme monokai	특정 색상 테마 사용
harlequin --locale en_US	숫자 형식 로캘 설정
harlequin --help	모든 CLI 옵션 표시

앱 내 키 바인딩

쿼리 편집기

키	설명
Ctrl+Enter	현재 쿼리 실행
Ctrl+j	현재 쿼리 실행 (대안)
Ctrl+o	SQL 파일 열기
Ctrl+s	현재 쿼리를 파일에 저장
Ctrl+n	새 쿼리 탭
Ctrl+w	현재 쿼리 탭 닫기
Ctrl+k	다음 쿼리 탭으로 전환
Tab	자동완성 제안 수락
Escape	자동완성 메뉴 닫기
F1	도움말 표시 / 컨텍스트 문서

결과 패널

키	설명
Ctrl+r	결과 패널로 포커스 전환
Ctrl+e	쿼리 편집기로 포커스 전환
화살표 키	결과 테이블 탐색
Ctrl+c	선택한 셀 복사

일반

키	설명
Ctrl+q	Harlequin 종료
Ctrl+b	데이터 카탈로그 사이드바 토글
F1	도움말

DuckDB 전용 기능

DuckDB는 기본 어댑터이며 강력한 기능을 지원합니다:

-- CSV 파일 직접 읽기
SELECT * FROM read_csv_auto('data.csv');

-- Parquet 파일 읽기
SELECT * FROM read_parquet('data.parquet');

-- JSON 파일 읽기
SELECT * FROM read_json_auto('data.json');

-- 원격 파일 쿼리
SELECT * FROM read_csv_auto('https://example.com/data.csv');

-- S3 파일 쿼리 (s3 어댑터 사용)
SELECT * FROM read_parquet('s3://bucket/data.parquet');

-- 여러 파일에서 데이터 집계
SELECT * FROM read_csv_auto('logs/*.csv');

설정 파일

자주 사용하는 연결 프로필을 저장하기 위한 설정 파일 생성:

프로필 설정

# ~/.config/harlequin/config.toml
# (또는 --config 플래그를 사용하여 경로 지정)

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

프로필 사용:

harlequin --profile local-pg

사용 가능한 어댑터

어댑터	설치 추가	연결 예제
DuckDB	(내장)	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
ODBC	odbc	일반 ODBC 연결
Trino	trino	Trino/Presto 클러스터
BigQuery	bigquery	Google BigQuery
Cassandra	cassandra	Apache Cassandra
ClickHouse	clickhouse	ClickHouse 데이터베이스
MotherDuck	(DuckDB 통해)	클라우드 DuckDB

일반적인 워크플로우

# 빠른 데이터 탐색 — CSV를 데이터베이스로 열기
harlequin
# 그런 다음 쿼리 편집기에서: SELECT * FROM read_csv_auto('data.csv') LIMIT 100;

# SQLite 데이터베이스 탐색 (예: 모바일 앱 DB)
harlequin -a sqlite app.db

# 개발을 위해 로컬 Postgres에 연결
harlequin -a postgres -h localhost -p 5432 -U dev -d myapp_dev

# 데이터베이스에 로드하지 않고 Parquet 파일 분석
harlequin
# 그런 다음: SELECT * FROM read_parquet('output/*.parquet');

Django 통합

# django-harlequin 설치
pip install django-harlequin

# Django DB에 연결된 Harlequin 실행
./manage.py harlequin

문제 해결

문제	해결 방법
어댑터를 찾을 수 없음	추가 기능과 함께 설치: uv tool install 'harlequin[postgres]'
연결 거부됨	호스트, 포트 및 데이터베이스 서버가 실행 중인지 확인
표시 문제	다른 터미널 시도 (Kitty, WezTerm, iTerm2 권장)
큰 테이블에서 느림	쿼리에 LIMIT 사용; 거대한 테이블에서 SELECT * 피하기
자동완성 누락	스키마가 있는 데이터베이스에 연결되어 있는지 확인

다른 SQL 도구와의 비교

기능	Harlequin	DBeaver	pgcli	usql
터미널에서 실행	예	아니오 (GUI)	예	예
다중 데이터베이스	예	예	Postgres만	예
자동완성	예	예	예	아니오
시각적 결과 테이블	예	예	기본	기본
파일 쿼리 (CSV, Parquet)	예 (DuckDB)	제한적	아니오	아니오
설정 프로필	예	예	예	아니오

리소스

• 공식 문서
• GitHub 저장소
• 어댑터 디렉토리