# Harlequin

> Harlequin is the SQL IDE for your terminal, and hsql is your agent's favorite SQL client: two interfaces to one query engine, for any database.

`harlequin` is the full-screen TUI: a data catalog, a query editor and a
results viewer, for a person at a keyboard. `hsql` is the command-line client
for scripts and agents: one statement or a file of them, several output
formats, compact results and safe defaults. They share adapters, config files,
profiles and a query engine, so you, your scripts and your agents can share one
tool.

Below is every page of the Harlequin documentation, grouped the way the
site's sidebar groups it. Each link is the page as markdown; drop the
`.md` for the rendered page at the same path.

- The whole corpus in one file: https://harlequin.sh/llms-full.txt (71 pages, ~168KB)
- The same index as JSON: https://harlequin.sh/api/docs/v1.json (a page: https://harlequin.sh/api/docs/v1/{slug}.json)
- The config file schema: https://harlequin.sh/schemas/config/v1.json

## Getting Started

- [Installing Harlequin](https://harlequin.sh/docs/getting-started.md): Harlequin is a Python program, and there are many ways to install and run it.
- [Running Harlequin](https://harlequin.sh/docs/getting-started/running.md): Once Harlequin is installed, you run it from the command line.
- [Using Harlequin](https://harlequin.sh/docs/getting-started/usage.md): A tour of Harlequin's Query Editor, Data Catalog and Results Viewer, and how to run your first query.
- [Using hsql](https://harlequin.sh/docs/getting-started/hsql.md): hsql is your agent's favorite SQL client.
- [Getting Help](https://harlequin.sh/docs/getting-started/help.md): Where to find help: harlequin --help, the in-app help screen, GitHub Discussions and Issues.

## The hsql CLI

- [The hsql CLI](https://harlequin.sh/docs/hsql.md): Reference for hsql, Harlequin's headless SQL client — the catalog, formats, exit codes, config files, safety options, the CLI reference and the agent skill.
- [Exit Codes and Streams](https://harlequin.sh/docs/hsql/exit-codes.md): hsql's six exit codes, what it writes to stdout and stderr, the --stats summary, and what --on-error does after a statement fails.
- [Exploring the Catalog](https://harlequin.sh/docs/hsql/catalog.md): How --catalog, --path and --catalog-search list a database's databases, schemas, relations and columns without running any SQL.
- [Formats and Layouts](https://harlequin.sh/docs/hsql/formats.md): Every hsql output format, the shorthand flags, the layout switches that shape a text layout, and how -o writes results to files.
- [Config Modes](https://harlequin.sh/docs/hsql/config.md): hsql's five --config modes — list-profiles, show, validate, schema and init — which read and write config files instead of running SQL.
- [Running Safely](https://harlequin.sh/docs/hsql/safety.md): The row limit, --read-only and --timeout, the adapter capabilities that back them, and how hsql refuses rather than pretending.
- [Differences from psql](https://harlequin.sh/docs/hsql/psql.md): What carries over from psql to hsql — -c, -f, -t, -A, -x — and the places where the same job has a different flag.
- [Reference: hsql CLI](https://harlequin.sh/docs/hsql/reference.md): Every hsql option, argument, format and exit code, generated from hsql itself and published with the release it came from.
- [The hsql Agent Skill](https://harlequin.sh/docs/hsql/skill.md): What hsql's Agent Skill teaches an agent, and three ways to install it — hsql --skill, the plugin marketplace, or the copy published here.

## Other Topics

- [Agent Docs](https://harlequin.sh/docs/agent-docs.md): Every page of these docs is also published as markdown and as JSON — .md twins, llms.txt, llms-full.txt, and a docs API.
- [Choosing a Theme](https://harlequin.sh/docs/themes.md): You can set a theme for Harlequin, passing the name of any Textual Theme to the --theme or -t option.
- [Exporting Data](https://harlequin.sh/docs/export.md): Copy results to the clipboard, or export them as CSV, Parquet, JSON, ORC or Feather.
- [Managing Transactions](https://harlequin.sh/docs/transactions.md): Different adapters handle transactions differently; many choose to auto-commit each executed query.
- [Reference: Default Bindings](https://harlequin.sh/docs/bindings.md): Harlequin uses keymaps to define sets of key bindings in the app.

## Database Adapters

- [Database Adapters](https://harlequin.sh/docs/adapters.md): Harlequin uses adapter plug-ins as a generic interface to any database.
- [Adapter: MySQL/MariaDB](https://harlequin.sh/docs/mysql.md): Install the MySQL adapter and connect Harlequin to a MySQL or MariaDB database.
- [Adapter: ODBC](https://harlequin.sh/docs/odbc.md): Connect Harlequin to SQL Server, Oracle, Teradata and other databases that ship an ODBC driver.
- [Adapter: Trino](https://harlequin.sh/docs/trino.md): Install the Trino adapter and connect Harlequin to a Trino cluster.
- [Adapter: ADBC](https://harlequin.sh/docs/adbc.md): Install the ADBC adapter and connect Harlequin to any database with an ADBC driver.
- [Adapter: RisingWave](https://harlequin.sh/docs/risingwave.md): Install the RisingWave adapter and connect Harlequin to a RisingWave instance.
- [Adapter: Wherobots](https://harlequin.sh/docs/wherobots.md): Install the Wherobots adapter and query WherobotsDB with the Wherobots Spatial SQL API.
- [Adapter: Cassandra](https://harlequin.sh/docs/cassandra.md): Install the Cassandra adapter and connect Harlequin to a Cassandra cluster.
- [Adapter: NebulaGraph](https://harlequin.sh/docs/nebulagraph.md): Install the NebulaGraph adapter and connect Harlequin to a NebulaGraph instance.
- [Adapter: Exasol](https://harlequin.sh/docs/exasol.md): Install the experimental Exasol adapter and connect Harlequin to an Exasol database.
- [Adapter: H2](https://harlequin.sh/docs/h2.md): Install the H2 adapter and connect Harlequin to embedded or server-based H2 databases over JDBC.

## Adapter: DuckDB

- [DuckDB Basic Usage](https://harlequin.sh/docs/duckdb.md): The DuckDB adapter ships with Harlequin; you do not need to do anything else to install it.
- [Initialization Scripts](https://harlequin.sh/docs/duckdb/initialization.md): Each time you start Harlequin, it will execute commands from a DuckDB initialization script.
- [Loading Extensions](https://harlequin.sh/docs/duckdb/extensions.md): Install and load DuckDB extensions at startup with the -e/--extension flag, signed or unsigned.
- [Transaction Handling](https://harlequin.sh/docs/duckdb/transactions.md): In DuckDB, statements are auto-committed by default.
- [MotherDuck](https://harlequin.sh/docs/duckdb/motherduck.md): You can use Harlequin with MotherDuck, just as you would use the DuckDB CLI

## Adapter: SQLite

- [SQLite Basic Usage](https://harlequin.sh/docs/sqlite.md): The SQLite adapter ships with Harlequin; you do not need to do anything else to install it.
- [Initialization Scripts](https://harlequin.sh/docs/sqlite/initialization.md): Each time you start Harlequin, it will execute commands from a SQLite initialization script.
- [Loading Extensions](https://harlequin.sh/docs/sqlite/extensions.md): Harlequin uses Python's distribution of SQLite, via its built-in sqlite3 library.
- [Transaction Handling](https://harlequin.sh/docs/sqlite/transactions.md): In SQLite, statements are auto-committed by default.

## Adapter: Postgres

- [Postgres Basic Usage](https://harlequin.sh/docs/postgres.md): You must install the harlequin-postgres package into the same environment as harlequin.
- [Multiple Databases](https://harlequin.sh/docs/postgres/multiple.md): Currently, the Postgres adapter only supports connections to a single database at a time.
- [Transaction Handling](https://harlequin.sh/docs/postgres/transactions.md): harlequin-postgres v0.3 and higher defines two transaction modes: Auto and Manual.

## Adapter: Redshift

- [Redshift Basic Usage](https://harlequin.sh/docs/redshift.md): Install the Redshift adapter and connect Harlequin to an Amazon Redshift cluster or Serverless workgroup.
- [Redshift Authentication](https://harlequin.sh/docs/redshift/auth.md): Connect Harlequin to Redshift with IAM credentials, Redshift Serverless, or a federated identity provider.
- [Redshift Data Catalog](https://harlequin.sh/docs/redshift/catalog.md): Browse, search, and act on Redshift databases, schemas, relations, and columns in the Data Catalog.

## Adapter: Snowflake

- [Snowflake Basic Usage](https://harlequin.sh/docs/snowflake.md): Install the Snowflake adapter and connect Harlequin to a Snowflake account.
- [Snowflake Authentication](https://harlequin.sh/docs/snowflake/auth.md): Choose a Snowflake authenticator, from password and SSO to key pair, OAuth, and workload identity.

## Adapter: BigQuery

- [BQ Installation and Configuration](https://harlequin.sh/docs/bigquery.md): Install the BigQuery adapter and connect Harlequin to a GCP project and location.
- [Auth and Permissions](https://harlequin.sh/docs/bigquery/auth.md): How the BigQuery adapter authenticates with Application Default Credentials, and the IAM permissions it needs.

## Adapter: Databricks

- [Installation and Basic Usage](https://harlequin.sh/docs/databricks.md): Install the Databricks adapter and connect Harlequin to a Databricks warehouse or cluster.
- [Initialization Scripts](https://harlequin.sh/docs/databricks/initialization.md): Each time you start Harlequin, it will execute SQL commands from a Databricks initialization script.

## Configuring Harlequin

- [Config Overview](https://harlequin.sh/docs/config-file.md): Typing in command-line options with every invocation of Harlequin can get tiring.
- [Creating Config Files](https://harlequin.sh/docs/config-file/creating-config.md): You can create config files manually, using any text editor.
- [Discovering Config Files](https://harlequin.sh/docs/config-file/discovery.md): Harlequin loads config files from the following locations.
- [Selecting a Profile](https://harlequin.sh/docs/config-file/profiles.md): All configs are nested within profiles.

## Viewing Files

- [Files Overview](https://harlequin.sh/docs/files.md): Show a file tree of local files or S3 objects in the Data Catalog, and insert paths into the editor.
- [Local Files](https://harlequin.sh/docs/files/local.md): Use --show-files (-f) to browse a local directory in the Data Catalog's Files tab.
- [Remote Objects (S3)](https://harlequin.sh/docs/files/remote.md): Before viewing remote objects, you must install the boto3 package in the same environment as Harlequin.

## Customizing Key Bindings

- [About Key Bindings](https://harlequin.sh/docs/keymaps.md): A key binding associates a key press, within a context, to an action.
- [Creating a Keymap](https://harlequin.sh/docs/keymaps/config.md): Keymaps can be defined in Harlequin config files, under the keymaps key.
- [Selecting Keymaps](https://harlequin.sh/docs/keymaps/usage.md): After you have created a keymap or installed a keymap plug-in, you need to configure Harlequin to use that keymap.

## Troubleshooting

- [Common Problems](https://harlequin.sh/docs/troubleshooting.md): An index of the things terminals get wrong: key bindings, copy-paste, colors, locale, timezones.
- [Key Bindings](https://harlequin.sh/docs/troubleshooting/key-bindings.md): Harlequin can only react to key presses that are sent to it from the Terminal it is running in.
- [Copying and Pasting](https://harlequin.sh/docs/troubleshooting/copying-and-pasting.md): Harlequin's Query Editor, Data Catalog, and Results Viewer support cut and copy, and its Query Editor supports paste.
- [Appearance](https://harlequin.sh/docs/troubleshooting/appearance.md): Fix colors, fonts and rendering by configuring your terminal for truecolor and a Nerd Font.
- [Locale](https://harlequin.sh/docs/troubleshooting/locale.md): Why numbers look unformatted in the C locale, and how to set --locale.
- [Windows Timezone Database](https://harlequin.sh/docs/troubleshooting/timezone-windows.md): Unlike other operating systems, Windows does not ship with an IANA-format timezone database.
- [DuckDB Version Mismatch](https://harlequin.sh/docs/troubleshooting/duckdb-version-mismatch.md): Pin the DuckDB version Harlequin installs when it cannot open a database file another DuckDB wrote.
- [Terminal Recommendations](https://harlequin.sh/docs/troubleshooting/terminal-recommendations.md): If you are using the default Mac Terminal or Windows Command Prompt, you may want to switch to a more modern terminal.

## Contributing to Harlequin

- [Ways to Contribute](https://harlequin.sh/docs/contributing.md): Ways to help: sponsoring, feedback, issues, pull requests, and writing an adapter.
- [Creating an Adapter](https://harlequin.sh/docs/contributing/adapter-guide.md): The HarlequinAdapter interface, entry points, and how to package an adapter for any relational database.