SPI_CURSO...PARAMLIST(3)

📦
version 18.6 · 21 versions
, in alpine 3.23, alpine 3.24, arch rolling, fedora 43, fedora 44, nixos 26.05, ubuntu resolute, ubuntu stonking

✨ SPI_CURSO...PARAMLIST(3) ✨

okay bestie, welcome to the SPI_cursor_open_with_paramlist page from the PostgreSQL 18.6 Documentation — yes the title is a whole mouthful, the man page authors really said "we're gonna truncate this and you're gonna deal" 💅 anyway it's giving C-spi-cursor-core and we're gonna eat it UP.

💖 NAME 💖

SPI_cursor_open_with_paramlist — set up a cursor using parameters 🎀

🌸 SYNOPSIS 🌸

Portal SPI_cursor_open_with_paramlist(const char *name,
                                      SPIPlanPtr plan,
                                      ParamListInfo params,
                                      bool read_only)

look at that signature. gorgeous. no notes. 🫶

🦋 DESCRIPTION 🦋

so what does this bad boy actually DO. SPI_cursor_open_with_paramlist sets up a cursor (and internally? it's literally a portal, iykyk) that will execute a statement prepared by SPI_prepare. ✨

it's equivalent to SPI_cursor_open — same energy, same vibes — EXCEPT the info about the parameter values you're passing to the query is presented differently. and the way it's different is that the ParamListInfo representation can be super convenient for passing down values that are already available in that format. like, no conversion era. no cap. it also supports use of dynamic parameter sets via hook functions specified in ParamListInfo. 🔥

and here's the part that lowkey matters a lot: the passed-in parameter data will be copied into the cursor's portal, so it can be freed while the cursor still exists. yes bestie you heard that right — free it, the portal already has its own copy, it's fine, go off. 💖

🎀 ARGUMENTS 🎀

  • const char * name — name for the portal, or NULL to let the system select a name for you (letting the system pick? main character move honestly 👑)
  • SPIPlanPtr plan — the prepared statement (the one returned by SPI_prepare)
  • ParamListInfo params — data structure containing parameter types and values; NULL if there are none
  • bool read_only — true for read-only execution

💜 RETURN VALUE 💜

a pointer to the portal containing the cursor. ✨

⚠️ and now the serious bit: there is no error return convention — any error will be reported via elog. so don't go checking the return value for errors, that's not a thing, the errors just show up through elog, periodt. 💀

🌈 that's the whole page bestie 🌈

every option, every arg, every caveat — we did not skip a single one, we would never 🙈

cute little sign-off moment: this whole thing comes from PostgreSQL 18.6, dated 2026, and it lives at SPI_CURSO...PARAMLIST(3) in the man pages. slay, go forth, and free your parameter data with confidence 💅✨🦋

📦 where this page comes from