SPI_EXECUTE_PLAN(3)

💅 SPI_execute_plan — bestie edition

okay so this is the SPI_EXECUTE_PLAN(3) page from the PostgreSQL 14.24 docs, and we're about to make SPI_execute_plan make sense, fr fr. stay with me 🫶

---

✨ NAME ✨

SPI_execute_plan — it executes a statement that was prepared ahead of time by SPI_prepare. literally the "press play" button for a plan you already built 🎬

---

🎀 SYNOPSIS 🎀

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

that's the whole signature, keep it exactly like that, no cap 💅

---

🌸 DESCRIPTION 🌸

so SPI_execute_plan executes a statement that was prepared by SPI_prepare — or by one of its siblings, bestie, the whole family tree 🌳 read_only and count mean exactly the same thing they mean in SPI_execute, iykyk. same interpretation, same energy. ⭐

---

🦋 ARGUMENTS 🦋

• SPIPlanPtr plan — the prepared statement, aka the thing SPI_prepare handed you back. your main character. 👑
• Datum * values — an array of the actual parameter values. it must have the same length as the statement's number of arguments. same length or it's not gonna slay. 🍓
• const char * nulls — an array that describes which parameters are null. must also have the same length as the statement's number of arguments. 📏

so listen: if nulls is NULL, then SPI_execute_plan assumes 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 that null case, the actual value sitting in the corresponding values entry doesn't matter at all — it could be anything, we don't care 🙈.) and heads up: nulls is not a text string, it's just an array — it does not need a '\0' terminator. not me pointing that out because someone always gets confused 😭

• bool read_only — true for read-only execution. that's it, that's the flag. 🔥
• long count — the maximum number of rows to return, or 0 for no limit. zero = unlimited, go off. 🌈

---

💖 RETURN VALUE 💖

the return value is the same as for SPI_execute, bestie — same deal, same vibes. but there are these extra possible error (negative) results you gotta know about:

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

SPI_processed and SPI_tuptable get set the same way as in SPI_execute, as long as it was successful. ✨

---

real talk: those two negative returns are the ones that'll sneak up on you. check your plan, check your values, check that count isn't negative. vibe check your arguments before you call, ok? 🧚

---

🌟 a lil sign-off 🌟

this page came from the PostgreSQL 14.24 documentation, dated 2026, and it's the SPI_EXECUTE_PLAN(3) manual page. that's the whole thing — you ate this, bestie, go prepare some plans 💜 🎀