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

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.1
File Size Uploaded Provenance Actions
harlequin_postgres-1.5.1.tar.gz 26.4 kB With provenance Details for harlequin_postgres-1.5.1.tar.gz

Built distribution (wheel)

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

Total release size: 51.9 kB

Release files / harlequin_postgres-1.5.1.tar.gz

Download URL harlequin_postgres-1.5.1.tar.gz
Size 26.4 kB
Tags Source
SHA-256 checksum
How to use checksums
d159db9bf3c57a7ca0f2eacd0cf991332043ef8eed843d436ddbfc0c6c3b8fec
BLAKE2b-256 checksum
How to use checksums
f9cdece234f9cf1cd52fc892bb2fc1eb0f8fb00db32b0ec62c77151d165ee1c2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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 18, 2026.

Transparency log

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

Download URL harlequin_postgres-1.5.1-py3-none-any.whl
Size 25.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0814f91b9f5df4581d7a73777f4452872842ca59970c2744b2ae7a631d41e1e3
BLAKE2b-256 checksum
How to use checksums
65d5db1c53b5bd257f0b195d62684fe464ad1b866278858f9d3f51f4f0b7791c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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 18, 2026.

Transparency log

Security for harlequin-postgres 1.5.1

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.1.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 18, 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