SPI_CURS...WITH_ARGS(3)

✨ SPI_cursor_open_with_args(3) — the PostgreSQL 18.6 glow-up ✨

okay bestie, sit down, hydrate, and let me tell you about SPI_cursor_open_with_args 💖 this one lives in the PostgreSQL 18.6 docs and it's giving "set up a cursor using a query and parameters" energy, periodt.

---

🌸 NAME 🌸

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)

like... look at that signature. iconic. no notes. 💅

---

💜 DESCRIPTION 💜

So what does it do, bestie? SPI_cursor_open_with_args sets up a cursor (internally, a portal) that will execute the specified query. That's the whole vibe. 🔥

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, you're basically already fluent, iykyk. ✨

Now here's the tea ☕ — for one-time query execution, this function should be preferred over SPI_prepare_cursor followed by SPI_cursor_open. But if the same command is going to be executed with many different parameters, either method might be faster, depending on the cost of re-planning versus the benefit of custom plans. it's giving "situationship with your query planner", honestly. 😭

The passed-in parameter data will be copied into the cursor's portal, so it can be freed while the cursor still exists. freeing your stuff early? self-care. 🫶

⚠️ heads up bestie: this function is now deprecated in favor of SPI_cursor_parse_open, which provides equivalent functionality using a more modern API for handling query parameters. she's still here, she still works, but the new girl is the moment. 💀

---

🌈 ARGUMENTS 🌈

• const char * name — name for portal, or NULL to let the system select a name. letting the system pick? delegating is a skill, honestly 👑
• const char * command — command string 🍓
• int nargs — number of input parameters ($1, $2, etc.)
• Oid * argtypes — an array of length nargs, containing the OIDs of the data types of the parameters 🦋
• Datum * values — an array of length nargs, containing the actual parameter values ✨
• 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. not me being an array not a string, she's different like that 💅

• bool read_only — true for read-only execution 🎀
• int cursorOptions — integer bit mask of cursor options; zero produces default behavior. zero = default = unbothered, moisturized, in her own lane 🌸

---

⭐ RETURN VALUE ⭐

Pointer to portal containing the cursor. 💖

🚨 but listen: there is no error return convention; any error will be reported via elog. so don't go checking for a NULL return like it's gonna tell you something, bestie. errors come through elog, that's the whole system. 💀

---

and that's the page!! 🎉

sending you the biggest vibes — this was PostgreSQL 18.6, dated 2026, and yes she's serving SPI_CURS...WITH_ARGS(3) energy from the very top to the very bottom. go forth and portal responsibly, bestie 🦋✨💖