Re: Proposal to allow setting cursor options on Portals

From: Sami Imseih <samimseih(at)gmail(dot)com>
To: Dave Cramer <davecramer(at)gmail(dot)com>
Cc: Hannu Krosing <hannuk(at)google(dot)com>, Robert Haas <robertmhaas(at)gmail(dot)com>, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us>, Jelte Fennema-Nio <postgres(at)jeltef(dot)nl>, Jacob Champion <jacob(dot)champion(at)enterprisedb(dot)com>, PostgreSQL Hackers <pgsql-hackers(at)lists(dot)postgresql(dot)org>, Heikki Linnakangas <hlinnaka(at)iki(dot)fi>
Subject: Re: Proposal to allow setting cursor options on Portals
Date: 2026-03-24 20:54:41
Message-ID: CAA5RZ0v8LeJ7NG8K+A2O8d3eCw=1-gndzTwiQDpW3SmDPNJpDg@mail.gmail.com
Views: Whole Thread | Raw Message | Download mbox | Resend email
Thread:
Lists: pgsql-hackers

> Well there are currently ways to name a portal with V3 so named portal doesn't make sense.
>
> _pq_.cursor would be fine.

I spent some time today on this, and implemented this as a new protocol
extension called _pq_.protocol_cursor, and the libpq option will also have
the same name. Maybe someone else has a better name, but I like this
as it differentiates from a sql-level cursor. Maybe someone has a better
suggestion.

All the cursor options can be passed, though CURSOR_OPT_BINARY is
irrelevant in the extended query protocol as noted here [1]. Binary output is
controlled by the result format codes on the FETCH instead. So,
CURSOR_OPT_BINARY can be passed as a cursor option, but will be
silently ignored.

I added a new test module libpq_protocol_cursor that expands the
tests to cover all options, except for cursor sensitivity. Also, there
are tests for multiple flags, enabling/disabling the extension and
unnamed portal being used ( which should not be allowed ).

A few other comments to earlier points:

> Also, should there also be an API such `PQholdablePortalEnabled` which
> takes a connection and

I did not implement this and instead rely on
if (cursorOptions != 0 && !conn->protocol_cursor_enabled) to reject the
usage of the API. So, if the API is called with cursor options but
protocol_cursor is not enabled, we reject the attempt. So, I am
not sure this Enabled() API has any value after thinking about it a bit more.

> # 5. Replace hex with constants defined in libpq-fe.h which mirror parsenodes.h
> for example 0x0020 → PQ_CURSOR_OPT_HOLD, etc.

Also, did not implement this since as mentioned earlier, I am not sure
how to keep these in sync with core. The docs do mention that
parsenodes.h is to be referenced for the bitmasks that are defined
as CURSOR_OPT_*. That may be good enough.

See v3 attached.

[1] https://www.postgresql.org/docs/18/protocol-flow.html#PROTOCOL-FLOW-EXT-QUERY

Attachment Content-Type Size
v3-0001-Add-_pq_.cursor-protocol-extension-for-cursor-opt.patch application/octet-stream 48.8 KB

In response to

Responses

Browse pgsql-hackers by date

  From Date Subject
Next Message Greg Burd 2026-03-24 21:01:12 Re: Expanding HOT updates for expression and partial indexes
Previous Message Nathan Bossart 2026-03-24 20:53:10 Re: [PATCH] Fix wrong argument to SOFT_ERROR_OCCURRED in timestamptz_date