Metadata-Version: 2.4
Name: harlequin-postgres
Version: 1.5.0
Summary: A Harlequin adapter for Postgres.
Author-email: Ted Conbeer <tconbeer@users.noreply.github.com>
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: duckdb>=1.4.2.dev0; python_version >= '3.14'
Requires-Dist: harlequin<3,>=2.11
Requires-Dist: psycopg[binary,pool]<4,>=3.2
Description-Content-Type: text/markdown

# harlequin-postgres

This project provides the Harlequin adapter for Postgres. For more information, see [harlequin.sh](https://harlequin.sh/docs/postgres/index).


## 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:

```bash
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](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING) as an argument:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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](https://harlequin.sh/docs/postgres/index).
