SPI_PREPARE_CURSOR(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_PREPARE_CURSOR 💖

okay bestie, so this one is SPI_PREPARE_CURSOR(3) from the PostgreSQL 18.6 docs, and it's literally the "get your statement ready but don't run it yet" girlie. she's giving preparation era, not execution era. 🎀

✨ NAME ✨

SPI_prepare_cursor — prepare a statement, without executing it yet

🌸 SYNOPSIS 🌸

SPIPlanPtr SPI_prepare_cursor(const char * command, int nargs,
                              Oid * argtypes, int cursorOptions)

🦋 DESCRIPTION 🦋

so SPI_prepare_cursor is identical to SPI_prepare, except — and this is the moment, the plot twist — it also lets you specify the planner's "cursor options" parameter. 💅

that parameter is a bit mask, and the values you can put in it are the ones shown in nodes/parsenodes.h for the options field of DeclareCursorStmt. iykyk. meanwhile SPI_prepare is out here always taking the cursor options as zero, no options, no thoughts, head empty. 😌

heads up: this function is now deprecated in favor of SPI_prepare_extended. she's still here, she still works, but she's not the main character anymore. 🫶

⭐ ARGUMENTS ⭐

  • const char * command — the command string. the actual SQL, the whole vibe, the script.
  • int nargs — number of input parameters, aka the $1, $2, etc. count them, bestie.
  • Oid * argtypes — a pointer to an array holding the OIDs of the data types of the parameters. it's giving "who are your parameters and what are they made of".
  • int cursorOptions — integer bit mask of cursor options; zero produces default behavior. zero = no notes, just default. 💖

🌈 RETURN VALUE 🌈

SPI_prepare_cursor has the same return conventions as SPI_prepare. same energy, same rules, no surprises. ✨

🎀 NOTES 🎀

the useful bits to set in cursorOptions include:

  • CURSOR_OPT_SCROLL
  • CURSOR_OPT_NO_SCROLL
  • CURSOR_OPT_FAST_PLAN
  • CURSOR_OPT_GENERIC_PLAN
  • CURSOR_OPT_CUSTOM_PLAN

and note in particular — like, in particular — that CURSOR_OPT_HOLD is ignored. she simply does not see it. don't count on it, fr fr. 💀

and that's the whole page, babe 💜 this was PostgreSQL 18.6, dated 2026, and it's the SPI_PREPARE_CURSOR(3) manual page — go forth and prepare those cursors responsibly, mwah 🫶✨

📦 where this page comes from