Skip to main content

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.

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.

Metadata

Release files for harlequin-postgres 1.6.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for harlequin-postgres 1.6.0
File Size Uploaded Provenance Actions
harlequin_postgres-1.6.0.tar.gz 28.0 kB With provenance Details for harlequin_postgres-1.6.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for harlequin-postgres 1.6.0
File Interpreter ABI Platform Actions
harlequin_postgres-1.6.0-py3-none-any.whl Python 3 none any Details for harlequin_postgres-1.6.0-py3-none-any.whl

Total release size: 55.0 kB

Release files / harlequin_postgres-1.6.0.tar.gz

Download URL harlequin_postgres-1.6.0.tar.gz
Size 28.0 kB
Tags Source
SHA-256 checksum
How to use checksums
48608904f81622493ff24f705b945ee4ff95c7b315d5c9fc81d9058204bc2104
BLAKE2b-256 checksum
How to use checksums
631909937776647585e0e9bb58f8f99d63159ad1b32bc52cf096fccf263806b7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.

Transparency log

Release files / harlequin_postgres-1.6.0-py3-none-any.whl

Download URL harlequin_postgres-1.6.0-py3-none-any.whl
Size 27.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
cfc75fe41711b0f8cd84511477e1751b7e0d9c3ef24a1fca5a7fd2bf51ec8c94
BLAKE2b-256 checksum
How to use checksums
0e34c328b93fda670b381e44c49a1d56765c2b74b7a8c785a08f811065dddd83
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.

Transparency log

Security for harlequin-postgres 1.6.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for harlequin_postgres-1.6.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page