SPI_EXECUTE_PLAN(3)

📦
version 18.6 · 21 versions
, in alpine 3.23, alpine 3.24, arch rolling, fedora 43, fedora 44, nixos 26.05, ubuntu resolute, ubuntu stonking

✨ SPI_EXECUTE_PLAN 💅

okay bestie, welcome to SPI_EXECUTE_PLAN(3), straight out of the PostgreSQL 18.6 Documentation 🫶 this is the one where you finally run the statement you prepped earlier. no cap, it's iconic.

🌸 NAME 🌸

SPI_execute_plan — execute a statement prepared by SPI_prepare 🎀

🦋 SYNOPSIS 🦋

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

💖 DESCRIPTION 💖

So SPI_execute_plan runs a statement that you already prepped with SPI_prepare — or literally any of its siblings, the whole fam ✨

And read_only and count? They mean exactly the same thing they mean in SPI_execute. same vibe, no notes 💅

👑 ARGUMENTS 👑

  • SPIPlanPtr plan — your prepared statement, aka the thing SPI_prepare handed back to you 🎀
  • Datum * values — an array of the actual parameter values. it must be the same length as the statement's number of arguments, periodt. no skipping.
  • const char * nulls — an array that says which parameters are null. also must be the same length as the statement's number of arguments. twin arrays fr fr 🌈

If nulls is NULL, then SPI_execute_plan just assumes none of the parameters are null. easy.

Otherwise, each entry in the nulls array should be ' ' if that parameter's value is non-null, or 'n' if that parameter's value is null. (and if it's null, the actual value sitting in the matching values entry literally doesn't matter, it's giving irrelevant 💀)

⚠️ heads up bestie: nulls is not a text string, it's just an array. so it does not need a '\0' terminator. don't add one, don't expect one.
  • 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 🫶 but with these extra possible error (negative) results:

  • 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 🙈

And if everything goes well? SPI_processed and SPI_tuptable get set exactly like in SPI_execute. slay 💅✨

anyway that's the whole page, mwah 💜 this was SPI_EXECUTE_PLAN(3) from PostgreSQL 18.6, dated 2026 — love that for us, go execute something iconic 🦋💖

📦 where this page comes from