From: dvarrazzo (@dvarrazzo) <noreply+dvarrazzo@github.com>
To: psycopg/psycopg <noreply+psycopg-psycopg@github.com>
Subject: [psycopg/psycopg] issue #1500: Wrap missing libpq functions in the pq module
Date: Tue, 17 Nov 2026 23:33:46 +0000
Message-ID: <gh-psycopg-psycopg-1500@github.com> (raw)
The `psycopg.pq` module wraps most of the libpq, but a few useful functions are missing. For Psycopg 3.4 we want to add the following.
## Pipeline
- [ ] `PQsendPipelineSync()` (libpq 17) -> `PGconn.send_pipeline_sync()`
Like `PQpipelineSync()`, but it doesn't flush the output buffer. Several syncs can then be sent with a single write, for instance in `executemany()` in pipeline mode.
## Error messages
- [ ] `PQsetErrorVerbosity()` -> `PGconn.set_error_verbosity()`
- [ ] `PQsetErrorContextVisibility()` -> `PGconn.set_error_context_visibility()`
- [ ] `PQresultVerboseErrorMessage()` -> `PGresult.verbose_error_message()`
They control how much detail error messages include: the SQLSTATE, the CONTEXT lines, the server source location. This needs two new enums, `pq.ErrorVerbosity` (`TERSE`, `DEFAULT`, `VERBOSE`, `SQLSTATE`) and `pq.ContextVisibility` (`NEVER`, `ERRORS`, `ALWAYS`).
## SSL information
- [ ] `PQsslAttribute()` -> `PGconn.ssl_attribute()`
- [ ] `PQsslAttributeNames()` -> `PGconn.ssl_attribute_names`
They report details of the SSL connection, such as the protocol, the cipher and the key size. They are marked as TODO in `_pq_ctypes.py`. `PQsslStruct()` and `PQgetssl()` return OpenSSL pointers, which are not useful from Python, so they are left out.
## Results
- [ ] `PQresultMemorySize()` (libpq 12) -> `PGresult.memory_size`
The memory used by a result. Useful to diagnose memory usage.
- [ ] `PQsetvalue()` -> `PGresult.set_value()`
- [ ] `PQcopyResult()` -> `PGresult.copy()`
We already wrap `PQmakeEmptyPGresult()` and `PQsetResultAttrs()`, so you can build the columns of a result, but you can't fill its rows.
## Notes
- Every new method needs both the Python and the C implementation, plus a `NotSupportedError` when the libpq loaded is too old, as for the other functions that need a recent libpq.
- Once these exist, we can decide whether to use them at a higher level: `send_pipeline_sync()` in `Pipeline`, the SSL attributes in `ConnectionInfo`, the error verbosity as a connection setting.
- OAuth functionalities are being added in #1190.
## Not planned
- Functions replaced by ones we already wrap: `PQrequestCancel`, `PQencryptPassword`, `PQoidStatus`, `PQsetNoticeProcessor`, `PQinitSSL`, and the old COPY API (`PQgetline`, `PQgetlineAsync`, `PQputline`, `PQputnbytes`, `PQendcopy`).
- Functions whose results we already get another way: `PQclientEncoding` and `PQsetClientEncoding` (we read and set the `client_encoding` parameter), and `PQpingParams` (`PGconn.ping()` takes a connection string).
- Callback hooks: the SSL key password hook and the events API. They can be considered separately if there is demand.
- `PQsocketPoll()`: we have our own wait functions.