SPI_PREPARE_CURSOR(3)

🌸 NAME 🌸

okay so bestie, this is SPI_prepare_cursor (you'll see it as SPI_PREPARE_CURSOR(3) up top) — and its whole job is to prepare a statement, without executing it yet. 💅✨

📜 SYNOPSIS 📜

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

💖 DESCRIPTION 💖

SPI_prepare_cursor is identical to SPI_prepare, except that it also lets you specify the planner's “cursor options” parameter. Iconic. It's a bit mask, and the values are shown in nodes/parsenodes.h for the options field of DeclareCursorStmt. Meanwhile SPI_prepare always takes the cursor options as zero. no cap.

🚨 heads-up: this function is now deprecated in favor of SPI_prepare_extended. So like, it still exists, but don't make it your main character if you're writing new stuff.

🎀 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. literally matching vibes. 🫶

⭐ NOTES ⭐

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

Note in particular that CURSOR_OPT_HOLD is ignored. 🙈

okay that's the whole page, bestie — source/version PostgreSQL 15.19, date 2026. mwah 💋