SPI_PREPARE_CURSOR(3)

🌸 NAME 🌸

Okay so bestie, this is SPI_prepare_cursor(3): it prepares a statement, without executing it yet. Iconic little setup step, no execution yet 💅.

✨ SYNOPSIS ✨

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

💖 DESCRIPTION 💖

SPI_prepare_cursor is literally identical to SPI_prepare, with one extra little slay: it also lets you specify the planner's “cursor options” parameter. That parameter is a bit mask, and its values are shown in nodes/parsenodes.h for the options field of DeclareCursorStmt. Meanwhile, SPI_prepare always takes the cursor options as zero.

Ngl, this function is now deprecated in favor of SPI_prepare_extended 💀. Not the vibe, but that's the note.

🎀 ARGUMENTS 🎀

• const char * command — the command string.
• int nargs — number of input parameters ($1, $2, etc.).
• Oid * argtypes — pointer to an array containing the OIDs of the data types of the parameters.
• int cursorOptions — integer bit mask of cursor options; zero produces default behavior.

🦋 RETURN VALUE 🦋

SPI_prepare_cursor has the same return conventions as SPI_prepare. No new return-value lore, bestie 🫶.

🌈 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 that CURSOR_OPT_HOLD is ignored — yes, ignored, so don't come for it 🙈.

okay bye bestie 💖 — this page is from PostgreSQL 16.15, dated 2026, and it's the SPI_PREPARE_CURSOR(3) manual page. periodt ✨