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.5.2

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.5.2
File Size Uploaded Provenance Actions
harlequin_postgres-1.5.2.tar.gz 26.9 kB With provenance Details for harlequin_postgres-1.5.2.tar.gz

Built distribution (wheel)

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

Total release size: 52.8 kB

Release files / harlequin_postgres-1.5.2.tar.gz

Download URL harlequin_postgres-1.5.2.tar.gz
Size 26.9 kB
Tags Source
SHA-256 checksum
How to use checksums
366e5e702476ed0e79f7c8b4ad3f0966fd23c9954247e4dd429e84b7328649bd
BLAKE2b-256 checksum
How to use checksums
57d0398eeb303f88cd16cd4fd4b90b3c27a17a51d37e456d99277d41dd577b1a
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 23, 2026.

Transparency log

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

Download URL harlequin_postgres-1.5.2-py3-none-any.whl
Size 25.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
40c219332d91f682f06aa52da784257d64b0464e880717f87fc46b66b8e8fdfb
BLAKE2b-256 checksum
How to use checksums
39c550b2d936da452e0fd547ed4055b3382b3e0c272b9b1bf6bb32d049f31599
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 23, 2026.

Transparency log

Security for harlequin-postgres 1.5.2

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.5.2.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 23, 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