SPI_CURS...WITH_ARGS(3)

🎀 NAME 🎀

okay bestie, you’re on the SPI_CURS...WITH_ARGS(3) page from the PostgreSQL 13.23 Documentation, and we’re about to make cursor setup make sense 💖

SPI_cursor_open_with_args — set up a cursor using a query and parameters ✨

---

🌸 SYNOPSIS 🌸

Portal SPI_cursor_open_with_args(const char *name,
                                 const char *command,
                                 int nargs, Oid *argtypes,
                                 Datum *values, const char *nulls,
                                 bool read_only, int cursorOptions)

---

🦋 DESCRIPTION 🦋

okay so SPI_cursor_open_with_args sets up a cursor — internally, a portal — that will execute the query you pass in. Most of the parameters have the same meanings as the corresponding parameters to SPI_prepare_cursor and SPI_cursor_open, so if you already know those two, you’re lowkey already halfway there 🫶

For one-time query execution, this function should be preferred over SPI_prepare_cursor followed by SPI_cursor_open. That’s the vibe: one-shot query, use this. But if the same command is going to be executed with many different parameters, either method might be faster — it depends on the cost of re-planning versus the benefit of custom plans. So it’s giving “situational”, not “always pick this one” 👑

The passed-in parameter data will be copied into the cursor’s portal, so it can be freed while the cursor still exists. Translation: your parameter data gets its own little portal home, and you don’t have to keep it alive afterward 💅

---

✨ ARGUMENTS ✨

• const char * name — name for the portal, or NULL to let the system select a name. Very “you handle it, bestie” of you 🌈
• const char * command — command string. This is the query itself, the main character of the whole operation 🎬
• int nargs — number of input parameters ($1, $2, etc.). Count them, don’t guess, fr fr 🔢
• Oid * argtypes — an array of length nargs, containing the OIDs of the data types of the parameters. It’s giving “type info, but make it array” 🧚
• Datum * values — an array of length nargs, containing the actual parameter values. The real ones. The payload 💖
• const char * nulls — an array of length nargs, describing which parameters are null. If nulls is NULL then SPI_cursor_open_with_args assumes that no parameters are null. Otherwise, each entry of the nulls array should be ' ' if the corresponding parameter value is non-null, or 'n' if the corresponding parameter value is null. (In the latter case, the actual value in the corresponding values entry doesn’t matter.) Note that nulls is not a text string, just an array: it does not need a '\0' terminator. Tiny but important detail, no cap 💀
• bool read_only — true for read-only execution. Set it to true when you’re just looking, not touching 👀
• int cursorOptions — integer bit mask of cursor options; zero produces default behavior. Zero is the “no notes, default vibes” choice ⭐

---

👑 RETURN VALUE 👑

Pointer to portal containing the cursor. Note there is no error return convention; any error will be reported via elog. So like, don’t go looking for a special error return value — it’s not that kind of function 😭

---

made with 💖 by the PostgreSQL 13.23 docs, 2025 — SPI_CURS...WITH_ARGS(3) vibes only 🫶