SPI_PREPARE_CURSOR(3)

💅 SPI_PREPARE_CURSOR(3) — prepare a statement, without executing it yet ✨

🏷️ 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

okay so SPI_prepare_cursor is literally identical to SPI_prepare, except it also allows specification of the planner's “cursor options” parameter. Cute extra dial, bestie. 🎛️

That parameter is a bit mask, and it has the values shown in nodes/parsenodes.h for the options field of DeclareCursorStmt. SPI_prepare always takes the cursor options as zero — no extra options, just default energy. 🎀

🚨 Heads up: this function is now deprecated in favor of SPI_prepare_extended. It still exists, but it's giving legacy, bestie. 💅

🧾 ARGUMENTS

• const char * command — command string. Like, the actual statement text goes here. 📝
• int nargs — number of input parameters ($1, $2, etc.). Count them, don't guess. 🔢
• Oid * argtypes — pointer to an array containing the OIDs of the data types of the parameters. Type info lives here. 🫶
• int cursorOptions — integer bit mask of cursor options; zero produces default behavior. Default vibes are at zero. 🎀

🔁 RETURN VALUE

SPI_prepare_cursor has the same return conventions as SPI_prepare. No plot twist — same rules, same energy. 💖

📝 NOTES

Useful bits to set in cursorOptions include CURSOR_OPT_SCROLL, CURSOR_OPT_NO_SCROLL, CURSOR_OPT_FAST_PLAN, CURSOR_OPT_GENERIC_PLAN, and CURSOR_OPT_CUSTOM_PLAN.

🚨 Note in particular: CURSOR_OPT_HOLD is ignored. Like, it does not do the thing here. Do not pass it expecting magic, bestie. 💀

💌 That’s the page, bestie — sourced from PostgreSQL 17.11, dated 2026, and filed under SPI_PREPARE_CURSOR(3). Mwah! 💋