SPI_CURSOR_PARSE_OPEN(3pg15)

okay bestie, you're on the SPI_CURSOR_PARSE_OPEN(3) page from the PostgreSQL 15.19 docs, and it's giving “set up a cursor using a query string and parameters” energy 💅✨

🎀 NAME 🎀

SPI_cursor_parse_open — set up a cursor using a query string and parameters.

✨ SYNOPSIS ✨

Portal SPI_cursor_parse_open(const char *name,
                             const char *command,
                             const SPIParseOpenOptions * options)

💖 DESCRIPTION 💖

okay so SPI_cursor_parse_open sets up a cursor (internally, a portal) that's gonna execute the query string you specify. no cap.

think of it as comparable to SPI_prepare_cursor followed by SPI_cursor_open_with_paramlist, except that parameter references within the query string are handled entirely by supplying a ParamListInfo object. iconic behavior, honestly.

if you're doing one-time query execution, this function should be preferred over SPI_prepare_cursor followed by SPI_cursor_open_with_paramlist. but if the same command is gonna run with many different parameters, either method might be faster — it depends on the cost of re-planning versus the benefit of custom plans. lowkey a tradeoff, iykyk.

normally, the options->params object should mark each parameter with the PARAM_FLAG_CONST flag, because a one-shot plan is always used for the query. periodt.

the parameter data you pass in gets copied into the cursor's portal, so you can free it while the cursor is still alive. cute and convenient 🫶.

🫶 ARGUMENTS 🫶

okay bestie, here's the cast:

• const char * name — name for portal, or NULL to let the system select a name.
• const char * command — command string.
• const SPIParseOpenOptions * options — struct containing optional arguments.

callers should always zero out the entire options struct first, then fill whichever fields they want to set. that's what keeps code forward-compatible: any fields added to the struct in the future will be defined to behave backwards-compatibly if they're zero. it's giving “future-proof your fave” ✨.

the currently available options fields are:

• ParamListInfo params — data structure containing query parameter types and values; NULL if none.
• int cursorOptions — integer bit mask of cursor options; zero produces default behavior.
• bool read_only — true for read-only execution.

👑 RETURN VALUE 👑

you get back a pointer to the portal containing the cursor. heads up: there is no error return convention; any error will be reported via elog. so yeah, no sneaky error-return situation here 💀.

---

— with love, PostgreSQL 15.19 · 2026 · SPI_CURSOR_PARSE_OPEN(3) 💖🦋