harlequin-postgres

This project provides the Harlequin adapter for Postgres. For more information, see harlequin.sh.

Installation

You must install the harlequin-postgres package into the same environment as harlequin. The best and easiest way to do this is to use uv to install Harlequin with the postgres extra:

uv tool install 'harlequin[postgres]'

Using Harlequin with Postgres

To connect to a Postgres database, run Harlequin with the -a postgres option and pass a Posgres DSN as an argument:

harlequin -a postgres "postgres://my-user:my-pass@localhost:5432/my-database"

Connection Options

You can also pass all or parts of the connection string as separate options. The following is equivalent to the above DSN:

harlequin -a postgres -h localhost -p 5432 -U my-user --password my-pass -d my-database

The supported connection options are:

host
port
dbname
user
password
passfile
require_auth
channel_binding
connect_timeout
sslmode
sslcert
sslkey

For descriptions of each option, run:

harlequin --help

Read-Only Mode

This adapter supports Harlequin's --read-only option:

harlequin --read-only -a postgres "postgres://my-user:my-pass@localhost:5432/my-database"

Every connection this adapter opens is configured with set session characteristics as transaction read only, so the server rejects any statement that would write, in both Auto and Manual transaction modes. If the server does not report default_transaction_read_only as on after connecting, Harlequin refuses to start.

Catalog Search

This adapter implements search_catalog(), so you can find an object without walking the catalog a level at a time:

hsql -a postgres "postgres://my-user:my-pass@localhost:5432/my-database" --catalog-search orders

A term matches a database, schema, relation, or column whose name contains it, case-insensitively. Relations and columns come from the connected database, since that is the database the catalog shows them for; the other databases on the server are matched by name, which is all the catalog's top level shows for them.

Search Path

When Harlequin connects, this adapter loads the relations in the schemas on the connection's search_path (usually just public), so autocomplete offers them right away and select * from my_table completes without qualifying the name or expanding the schema in the Data Catalog. The rest of the catalog still loads as you browse it.

The path is whatever this connection resolves, so setting it any of the usual ways works, including in the DSN:

harlequin -a postgres "postgres://my-user@localhost:5432/my-database?options=-csearch_path%3Danalytics,public"

Environment Variables

Harlequin's Postgres driver will load connection information from the standard PG* environment variables. Any options supplied at the command-line will override environment variables.

Manual Transactions

To use Manual transaction mode, click on the label in the Run Query Bar to toggle the transaction mode from Auto to Manual.

Further Documentation

For more information, see the Harlequin Docs.