SPI_EXECUTE_EXTENDED(3)

✨ NAME ✨

SPI_execute_extended — bestie, it runs a command, but the parameters come from outside the command text 💅

---

🌸 SYNOPSIS 🌸

int SPI_execute_extended(const char *command,
                         const SPIExecuteOptions * options)

---

🦋 DESCRIPTION 🦋

okay so SPI_execute_extended executes a command that might include references to externally supplied parameters. The command text points at a parameter by writing $n, and the options->params object (if you actually pass one) hands over the values and the type info for each of those lil $n symbols. You can also stack a bunch of other execution options into the options struct, so like, it's a whole vibe buffet ✨

The options->params object should normally mark each parameter with the PARAM_FLAG_CONST flag, because a one-shot plan is always used for the query. no cap, always. 🫶

And if options->dest is not NULL? Then result tuples get passed straight to that object as the executor generates them, instead of being accumulated into SPI_tuptable. Using a caller-supplied DestReceiver object is particularly helpful for queries that might generate many tuples, since the data can be processed on-the-fly instead of piling up in memory. it's giving efficiency, it's giving main character energy 🔥

---

💖 ARGUMENTS 💖

• const char * command — the command string, literally the thing you want run 🎀
• const SPIExecuteOptions * options — a struct containing optional arguments, aka the little bag of settings

🚨 IMPORTANT BESTIE ALERT 🚨 Callers should always zero out the entire options struct, and then fill in whichever fields they want to set. This is how you keep your code forward compatible — any fields that get added to the struct in the future will be defined to behave backwards-compatibly if they are zero. so zero it first, fr fr. don't skip this. 🙈

the currently available options fields are… 💅

• ParamListInfo params — data structure containing query parameter types and values; NULL if none ⭐
• bool read_only — true for read-only execution 🌈
• bool allow_nonatomic — true allows non-atomic execution of CALL and DO statements (but heads up, this field is ignored unless the SPI_OPT_NONATOMIC flag was passed to SPI_connect_ext) 😭
• bool must_return_tuples — if true, raise error if the query is not of a kind that returns tuples (and to be clear, this does not forbid the case where it happens to return zero tuples — zero tuples is still a valid tuple-returning query, okurrr) 💀
• uint64 tcount — maximum number of rows to return, or 0 for no limit 👑
• DestReceiver * dest — DestReceiver object that will receive any tuples emitted by the query; if NULL, result tuples are accumulated into a SPI_tuptable structure, as in SPI_execute 🎀
• ResourceOwner owner — This field is present for consistency with SPI_execute_plan_extended, but it is ignored, since the plan used by SPI_execute_extended is never saved. it's literally just there for the vibes ✨

---

🎀 RETURN VALUE 🎀

The return value is the same as for SPI_execute. (yes, that's the whole tea ☕)

When options->dest is NULL, SPI_processed and SPI_tuptable are set as in SPI_execute. 🌸

When options->dest is not NULL, SPI_processed is set to zero and SPI_tuptable is set to NULL. So if a tuple count is required, the caller's DestReceiver object must calculate it. that's on you bestie, the function is not doing it for you 💅😭

---

and that's the whole page!! brought to you by PostgreSQL 18.6, documented back in 2026 — mwah, love that for us 🫶✨💖