SPI_CURS...WITH_ARGS(3)

✨ SPI_CURS...WITH_ARGS ✨

okay so bestie, buckle up, we're in the PostgreSQL 17.11 docs, section 3 — the C-functions-for-server-programmers zone 💅 this one's called SPI_cursor_open_with_args, and it's literally the "open a cursor with args in one shot" girlie. no cap.

---

🌸 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)

she takes a lot of arguments, i know, but it's giving "one function to rule them all" energy 👑

---

💖 DESCRIPTION 💖

so SPI_cursor_open_with_args sets up a cursor (internally, a portal, iykyk) that will execute the query you hand it. 🦋 most of the parameters mean the exact same thing as the corresponding parameters to SPI_prepare_cursor and SPI_cursor_open — like, same vibes, same semantics, no plot twist.

for one-time query execution, this function is the one you should prefer over SPI_prepare_cursor followed by SPI_cursor_open. like, just use the cute combined one, bestie 🫶 but — and this is important — if the same command is gonna be executed with many different parameters, either method might be faster, depending on the cost of re-planning versus the benefit of custom plans. so it's genuinely a "it depends" situation, not a "one is always better" situation. ngl that's just how it is 😭

the passed-in parameter data will be copied into the cursor's portal, so you can free it while the cursor still exists. yes, really — free it, she's got her own copy, she doesn't need yours anymore ✨

💀 deprecation warning, 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. so like... she still works, but she's lowkey the older sister who's been replaced by a cooler, more modern API. use SPI_cursor_parse_open for new stuff, periodt.

---

🎀 ARGUMENTS 🎀

• const char * name — name for the portal, or NULL to let the system select a name for you. the system's got taste, she'll pick something 🧚
• const char * command — the command string itself. the actual query, the main character of this whole operation 👑
• int nargs — number of input parameters ($1, $2, etc.). count them carefully bestie, no cap 🔥
• Oid * argtypes — an array of length nargs, containing the OIDs of the data types of the parameters. so like, one Oid per parameter, in order, don't skip any 🌈
• Datum * values — an array of length nargs, containing the actual parameter values. the real ones. the content 💜
• const char * nulls — an array of length nargs, describing which parameters are null. this is the spicy one, so listen up 🙈

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 — it's literally being ignored, she doesn't care 💀)

and this is the part everyone gets wrong: note that nulls is not a text string, just an array — it does not need a '\0' terminator. don't add one. she's built different 🦋

• bool read_only — true for read-only execution. set it to true and she'll behave 🎀
• int cursorOptions — integer bit mask of cursor options; zero produces default behavior. zero = default vibes, no notes ✨

---

👑 RETURN VALUE 👑

pointer to the portal containing the cursor. 🫶

and like... note there is no error return convention — any error will be reported via elog. so don't go checking for NULL expecting a cute little error signal, because that's not how she rolls. if something goes wrong, elog is gonna yell about it, not return a value. fr fr 😭

---

💡 tiny reminder from your girl: this is the deprecated one, so if you're starting fresh, SPI_cursor_parse_open is right there waiting for you. iykyk 💅

---

okay that's the whole page!! huge shoutout to the PostgreSQL 17.11 docs crew, this page is dated 2026, and the manual section is SPI_CURS...WITH_ARGS(3) — mwah, love you, go write some slay server-side C code for me 💖✨🎀🦋🌸💅🫶