SPI_PREPARE_CURSOR(3)

✨ SPI_prepare_cursor(3) ✨

Okay bestie, gather round 💖 this page is literally about preparing a statement and not executing it yet. It’s giving “prep now, run later” energy. No cap.

---

🎀 NAME 🎀

SPI_prepare_cursor — prepare a statement, without executing it yet. That’s the whole vibe: prep the statement, do not run it yet, periodt.

✨ SYNOPSIS ✨

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

💖 DESCRIPTION 💖

SPI_prepare_cursor is identical to SPI_prepare, except it also lets you specify the planner’s “cursor options” parameter. Yes, that’s the extra little sparkle ✨.

That parameter is a bit mask, and its values are the ones shown in nodes/parsenodes.h for the options field of DeclareCursorStmt. Meanwhile, SPI_prepare always takes the cursor options as zero — no options, just zero, default behavior.

🚨 Important: this function is now deprecated in favor of SPI_prepare_extended. Like, it’s still a thing, but it’s not the main character anymore. Choose SPI_prepare_extended if you’re starting fresh. 💅

🦋 ARGUMENTS 🦋

• const char * command — the command string. It’s a string, bestie.
• 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. It’s a pointer, it points at the OID array, you got this.
• int cursorOptions — integer bit mask of cursor options; zero produces default behavior. Zero = default. Simple as that.

🌈 RETURN VALUE 🌈

SPI_prepare_cursor has the same return conventions as SPI_prepare. So if you know how SPI_prepare returns, that’s the exact same deal here. No new drama.

💅 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

And note in particular that CURSOR_OPT_HOLD is ignored. Not “handled differently,” not “extra special” — ignored. So don’t come for CURSOR_OPT_HOLD, okay? 🙈

---

Signed, sealed, and slayed by PostgreSQL 14.24 Documentation, dated 2026. That’s the source/version and date, bestie, right at the bottom where it belongs. 🫶