Harlequin: The Revolutionary Terminal SQL IDE Developers Love

Stop context-switching between your terminal and clunky GUI database tools. Harlequin delivers a full-featured SQL IDE directly in your command line, transforming how you interact with databases forever. This modern, blazing-fast tool combines the power of DuckDB, SQLite, and dozens of other databases with a sleek terminal interface that keeps you in your flow state.

In this deep dive, you'll discover why thousands of developers are abandoning traditional database clients for Harlequin. We'll walk through installation, real-world code examples, advanced configurations, and performance optimizations that will supercharge your database workflow. Whether you're a data analyst, backend engineer, or full-stack developer, Harlequin will become your secret weapon for database productivity.

What is Harlequin?

Harlequin is the SQL IDE for your terminal—a revolutionary open-source tool that brings the full power of modern database clients directly to your command line interface. Created by Ted Conbeer and maintained by a growing community of contributors, Harlequin solves the fundamental friction point that has plagued developers for decades: the constant context switching between terminal work and graphical database tools.

Built with Python 3.9+ and powered by the Textual framework for rich terminal applications, Harlequin delivers a sleek, keyboard-driven interface that feels native to developers who live in their terminals. The tool defaults to DuckDB, the high-performance analytical database, but its true power lies in its adapter-based architecture that supports connections to dozens of database systems including PostgreSQL, MySQL, SQLite, Snowflake, BigQuery, and more.

Harlequin is trending because it perfectly captures the modern developer's desire for fast, keyboard-centric workflows without sacrificing features. Unlike traditional CLI database clients that feel archaic, Harlequin provides syntax highlighting, autocompletion, a data catalog browser, query history, and result export capabilities—all rendered beautifully in your terminal. It's the missing piece in the terminal-based development toolchain, completing the circle for developers who've already embraced tools like Neovim, tmux, and modern shells.

Key Features That Make Harlequin Essential

Multi-Database Powerhouse Through Adapters Harlequin's plugin architecture is its crown jewel. The tool ships with built-in DuckDB and SQLite adapters, but you can extend it to support virtually any database. Adapters are distributed as separate Python packages that install alongside Harlequin, creating a modular ecosystem where you only load what you need. This design keeps the core lightweight while offering unlimited extensibility.

Rich Terminal User Interface Forget everything you know about terminal database clients. Harlequin leverages Textual to deliver a modern, split-pane interface with resizable panels, smooth scrolling, and intuitive navigation. The UI includes a query editor with full syntax highlighting, a results grid that handles millions of rows, a searchable data catalog tree, and a query history panel. Everything is keyboard-optimized for terminal ninjas.

Intelligent Query Editor The editor provides real-time SQL syntax highlighting, auto-indentation, and context-aware autocompletion that suggests table names, column names, and SQL keywords as you type. It supports multiple queries in a single editor window and allows you to execute specific queries by selecting them. The editor remembers your query history across sessions, so you can recall complex queries with a few keystrokes.

Advanced Data Catalog Browser Navigate your database schema effortlessly with the integrated data catalog. Browse tables, views, and columns in a tree structure. The catalog displays column data types, primary keys, and foreign key relationships. For large databases, the search function instantly filters objects, making it trivial to find that one table buried in hundreds of schemas.

Theme System and Customization Harlequin respects your terminal aesthetic. Choose from multiple built-in themes including dark, light, and popular color schemes like Monokai and Dracula. You can create custom themes by defining colors for every UI element. Beyond themes, customize key bindings to match your muscle memory from Vim, Emacs, or other editors.

File Picker Integration The built-in file picker lets you navigate your local filesystem without leaving Harlequin. Open SQL scripts, export query results to CSV or Parquet, and manage database files. The file picker supports favorites, quick directory jumping, and integrates with remote filesystems when using cloud databases.

Configuration Profiles Tired of typing long connection strings? Harlequin supports TOML-based configuration files where you define named profiles for different databases. A single command like harlequin --profile production connects you instantly. Profiles can specify adapters, connection strings, themes, keymaps, and all other options.

Django Integration The django-harlequin package provides seamless integration with Django projects. Run ./manage.py harlequin to launch Harlequin pre-configured with your Django database settings, making database exploration during development frictionless.

Real-World Use Cases Where Harlequin Dominates

Data Analyst Crunching Local Files You're analyzing a 10GB CSV file on your laptop. Instead of loading it into a heavy BI tool, you launch Harlequin with harlequin data.csv. Harlequin's DuckDB adapter automatically infers the schema and lets you run analytical queries at lightning speed. You join the CSV with existing DuckDB tables, export results to Parquet, and never leave your terminal workflow. The keyboard shortcuts let you iterate through queries faster than any GUI tool could respond.

Backend Engineer Debugging Production PostgreSQL It's 2 AM and production is slow. You SSH into your server, but you don't want to install a GUI tool. With Harlequin installed, you run harlequin --adapter postgres "postgresql://..." and instantly explore slow query logs. You use the data catalog to check indexes, run EXPLAIN ANALYZE queries with syntax highlighting that makes execution plans readable, and export findings to share with your team. The terminal interface means you can work efficiently even over laggy SSH connections.

Data Engineer Managing Multiple SQLite Databases Your ETL pipeline creates hundreds of SQLite databases. You need to quickly inspect data quality across them. Harlequin lets you open multiple databases simultaneously: harlequin -a sqlite "db1.db" "db2.db" "db3.db". The UI shows each database in a separate tree, and you can run cross-database queries. The file picker helps you navigate between different project directories, and you save common quality-check queries in your history for reuse.

Full-Stack Developer Using Django You're building a Django application and need to inspect the database during development. Instead of using Django's basic dbshell, you install django-harlequin. Now ./manage.py harlequin gives you a rich IDE with autocomplete for your Django models' fields, the ability to save complex ORM-generated queries, and a beautiful interface that makes database exploration enjoyable. The configuration automatically picks up your Django settings, including database routers.

Step-by-Step Installation & Setup Guide

Method 1: Using uv (Strongly Recommended)

The fastest and cleanest way to install Harlequin is using uv, the modern Python package installer. This approach isolates Harlequin in its own environment and automatically adds it to your PATH.

First, install uv by running this command in your POSIX shell:

curl -LsSf https://astral.sh/uv/install.sh | sh

For Windows PowerShell users, execute:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Once uv is installed, install Harlequin as a tool:

uv tool install harlequin

This command creates an isolated environment, installs Harlequin and its dependencies, and makes the harlequin command available globally. You can verify the installation by running:

harlequin --version

Method 2: Using pip or pipx

If you prefer traditional Python tooling, ensure you have Python 3.9 or newer installed. Then run:

pip install harlequin

For better isolation, use pipx:

pipx install harlequin

Method 3: Using Homebrew

macOS and Linux users can install via Homebrew. Note that this community-maintained formula includes several adapters (Postgres, MySQL/MariaDB, ODBC), making it larger but more convenient:

brew install harlequin

Installing Database Adapters

Harlequin's power comes from adapters. Let's install the PostgreSQL adapter using uv:

uv tool install 'harlequin[postgres]'

You can install multiple adapters simultaneously:

uv tool install 'harlequin[postgres,mysql,s3]'

For a complete list of available adapters, visit harlequin.sh/docs/adapters.

Environment Setup and Verification

After installation, verify Harlequin is in your PATH:

which harlequin

If using uv, the tool should be available immediately. For pip installations, you may need to add ~/.local/bin to your PATH. Add this to your shell profile:

export PATH="$HOME/.local/bin:$PATH"

Test your installation by launching an in-memory DuckDB session:

harlequin

You should see Harlequin's interface launch in your terminal. Press F1 for help or Ctrl+C to exit.

REAL Code Examples from the Repository

Let's explore actual code examples from Harlequin's documentation, with detailed explanations of each command and its options.

Example 1: Installing Harlequin with uv

# Install uv first - the modern Python package manager
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install Harlequin as an isolated tool
uv tool install harlequin

The first command downloads and executes uv's installation script. The -L flag follows redirects, -sSf provides silent, fail-fast operation. The second command uses uv's tool install feature, which creates a dedicated virtual environment for Harlequin and symlinks its executable to your PATH. This approach prevents dependency conflicts and makes uninstallation clean.

Example 2: Installing with Database Adapters

# Install Harlequin with PostgreSQL adapter
uv tool install 'harlequin[postgres]'

# Install multiple adapters for polyglot database work
uv tool install 'harlequin[postgres,mysql,s3]'

These commands demonstrate Harlequin's adapter system. The square bracket syntax ([postgres]) tells uv to install extra dependencies defined in Harlequin's package metadata. Each adapter package contains the database driver and connection logic. Installing multiple adapters lets you switch between database types using the --adapter flag without reinstalling.

Example 3: Running Harlequin with DuckDB

# Launch in-memory DuckDB session (default)
harlequin

# Open existing DuckDB database files
harlequin "path/to/duck.db" "another_duck.db"

The first command launches Harlequin with DuckDB's in-memory mode, perfect for ad-hoc analysis. The second command opens multiple persistent DuckDB databases simultaneously. Harlequin creates the files if they don't exist. DuckDB's columnar storage makes this ideal for analytical workloads on local files.

Example 4: Using Harlequin with SQLite

# Launch in-memory SQLite database
harlequin --adapter sqlite

# Open SQLite database files with short alias
harlequin -a sqlite "path/to/sqlite.db" "another_sqlite.db"

Here we explicitly specify the SQLite adapter using --adapter sqlite (or its short form -a). SQLite's serverless architecture makes it perfect for embedded databases and mobile development. Harlequin's adapter system normalizes the interface across databases, so the same keyboard shortcuts and UI work regardless of backend.

Example 5: Django Integration

# After installing django-harlequin
./manage.py harlequin

This command, provided by the django-harlequin package, reads your Django project's DATABASES setting and launches Harlequin with the correct adapter and connection parameters. It handles complex setups like database routers, multiple databases, and custom settings automatically, bridging the gap between Django's ORM and raw SQL exploration.

Advanced Usage & Best Practices

Configuration Profiles for Instant Connections

Create a ~/.harlequin.toml file to define connection profiles:

[profile.production]
adapter = "postgres"
conn_str = ["postgresql://user:pass@host/db"]
theme = "monokai"

[profile.analytics]
adapter = "duckdb"
conn_str = ["~/data/analytics.duckdb"]
show_files = true

Now connect with harlequin --profile production. This eliminates memorizing connection strings and ensures consistent settings across sessions.

Keyboard Shortcut Mastery

Harlequin's default keymap uses Vim-style navigation. Press Ctrl+O to open the file picker, Ctrl+K to search the data catalog, and F5 to execute queries. Customize bindings in your config file:

[keymap]
execute_query = "ctrl+enter"
quit = "ctrl+q"

Query Optimization Workflow

For large result sets, use DuckDB's LIMIT clause initially, then Harlequin's export feature to save full results. Press Ctrl+E to export the current result set to CSV or Parquet. This keeps the UI responsive while allowing you to work with complete datasets offline.

Theming for Different Environments

Define different themes for production vs. development to avoid dangerous mistakes:

[profile.production]
theme = "red_alert"  # Custom theme with red background

[profile.development]
theme = "github_dark"

Adapter Version Pinning

When using Harlequin with specific DuckDB versions, pin the adapter in your requirements:

uv tool install 'harlequin[duckdb]==0.9.0'

This prevents version mismatches that can cause compatibility issues.

Comparison with Alternatives

Why Choose Harlequin?

Unlike single-database CLI tools, Harlequin provides a unified interface across all your databases. Compared to GUI tools, it launches instantly, works perfectly over SSH, and consumes minimal resources. The adapter architecture means you learn one tool and apply it everywhere, while GUI tools force you to adapt to different interfaces for each database.

Frequently Asked Questions

What databases does Harlequin support? Harlequin ships with DuckDB and SQLite adapters. Install additional adapters for PostgreSQL, MySQL, Snowflake, BigQuery, Oracle, SQL Server, ClickHouse, and 15+ others. The adapter ecosystem grows continuously through community contributions.

How is Harlequin different from pgcli or mycli? pgcli and mycli are single-database tools with basic autocomplete. Harlequin is a full IDE with a rich UI, multi-database support, file picking, theming, and configuration profiles. It's designed for developers who need more than a REPL but want to stay in the terminal.

Can I use Harlequin with my existing DuckDB installation? Yes. Harlequin uses DuckDB as a library, but you can control the version by installing a specific adapter version. See the troubleshooting guide at harlequin.sh for handling version mismatches with external DuckDB installations.

Is Harlequin really faster than GUI tools? For local analytical workloads, Harlequin with DuckDB often outperforms GUI tools because it runs in-process without network overhead. For remote databases, performance depends on connection speed, but the lightweight UI renders faster than Java-based GUIs like DBeaver.

How do I customize themes and key bindings? Create a ~/.harlequin.toml file. Define themes under [theme] sections and keymaps under [keymap]. Press F1 in Harlequin to see the default bindings and configuration examples. The documentation at harlequin.sh provides complete theme customization guides.

Does Harlequin work on Windows? Absolutely. Harlequin runs on Linux, macOS, and Windows. The uv installation method works cross-platform, and the Textual framework ensures the UI renders correctly in Windows Terminal, PowerShell, and WSL.

How can I contribute to Harlequin? Visit the GitHub repository and check CONTRIBUTING.md. Contributions welcome for new adapters, bug fixes, documentation, and themes. Join GitHub Discussions to connect with the community.

Conclusion

Harlequin represents a paradigm shift in database tooling. By bringing a full-featured IDE to the terminal, it eliminates the productivity-killing context switches that have plagued developers for years. Its adapter architecture, blazing DuckDB performance, and gorgeous Textual UI make it the ultimate choice for modern developers who demand both power and speed.

I've personally replaced three different database clients with Harlequin, and the workflow improvement is undeniable. The ability to launch a full IDE with harlequin --profile analytics and immediately query gigabytes of data is transformative. The keyboard-centric design respects your terminal workflow while providing visual feedback that CLI tools lack.

Ready to revolutionize your database workflow? Install Harlequin today using uv tool install harlequin and experience the future of terminal-based development. Star the GitHub repository to support the project and stay updated on new adapters and features. Your terminal will thank you.