SPI_EXECUTE_PLAN(3)

💅 SPI_EXECUTE_PLAN(3) — bestie, let's run that prepared statement ✨

okay so real talk, this one lives in the PostgreSQL 16.15 docs, it's part of the SPI fam, and it's lowkey iconic. stay with me 🫶

---

✨ NAME ✨

SPI_execute_plan — bestie, this is literally the function that executes a statement you already prepared with SPI_prepare. no cap. 🎀

---

🌸 SYNOPSIS 🌸

int SPI_execute_plan(SPIPlanPtr plan, Datum * values, const char * nulls,
                     bool read_only, long count)

---

🦋 DESCRIPTION 🦋

so SPI_execute_plan executes a statement that was prepared by SPI_prepare or one of its siblings 👑. and the way that read_only and count work — they have the exact same interpretation as in SPI_execute. periodt, that's the whole vibe check. 💅

---

💖 ARGUMENTS 💖

• SPIPlanPtr plan — the prepared statement (the one you got back from SPI_prepare) 🎀
• Datum * values — an array of the actual parameter values. it must have the same length as the statement's number of arguments. don't skip, don't shrink, don't be cute about it 🫶
• const char * nulls — an array that says which of the params are null. same rule: it must have the same length as the statement's number of arguments.

so here's the tea 🍓: if nulls is NULL, then SPI_execute_plan just assumes no parameters are null. otherwise, each entry of the nulls array should be ' ' if the matching parameter value is non-null, or 'n' if the matching parameter value is null. (and in that null case? the actual value sitting in the corresponding values entry genuinely doesn't matter, so like... don't stress 🙈) also super important — nulls is not a text string, it's just an array, so it does not need a '\0' terminator. no trailing weirdness required ✨

• bool read_only — true for read-only execution 💜
• long count — maximum number of rows to return, or 0 for no limit 🔥

---

🌈 RETURN VALUE 🌈

the return value is the same as for SPI_execute, plus these extra possible error (negative) results — heads up bestie, negative means something went sideways 💀:

• SPI_ERROR_ARGUMENT — if plan is NULL or invalid, or count is less than 0
• SPI_ERROR_PARAM — if values is NULL and plan was prepared with some parameters

and if it all slays successfully, SPI_processed and SPI_tuptable are set as in SPI_execute. ⭐

---

ngl, the vibe here is: prepare once, execute many. but do your argument arrays right or the error codes will come for you 😭

---

okay that's the whole page, you ate it up fr fr 🧚💖 this iconic little number is from PostgreSQL 16.15, dated 2026, and it's SPI_EXECUTE_PLAN(3) — go forth and execute, bestie 👑🌸