SPI_MODIFYTUPLE(3)

💅 SPI_MODIFYTUPLE(3) — the SPI_modifytuple glow-up page ✨

okay so bestie, welcome to the SPI_MODIFYTUPLE page from the PostgreSQL 16.15 docs — we're doing a little wardrobe change on a row and honestly it's giving main character energy 🎀

---

✨ NAME ✨

SPI_modifytuple — create a row by replacing selected fields of a given row 🌸

🦋 SYNOPSIS 🦋

HeapTuple SPI_modifytuple(Relation rel, HeapTuple row, int ncols,
                          int * colnum, Datum * values, const char * nulls)

💖 DESCRIPTION 💖

okay so here's the vibe: SPI_modifytuple creates a new row by substituting new values for selected columns, and it copies the original row's columns at all the other positions. The way it just... does the work for you 🫶

important!! the input row is not modified. she's untouched, she's iconic, we don't touch her 💅

The new row gets returned in the upper executor context — that's where she lives now ✨

Also, big caveat: this function can only be used while connected to SPI. If you're not connected, it returns NULL and sets SPI_result to SPI_ERROR_UNCONNECTED. it's giving "no connection no service" 😭

🎀 ARGUMENTS 🎀

• Relation rel — used only as the source of the row descriptor for the row. lowkey ngl, passing a relation rather than a row descriptor is a misfeature (the docs literally said it, not me 🙈).
• HeapTuple row — row to be modified. the before pic 🥰
• int ncols — number of columns to be changed. how many glow-ups we doing.
• int * colnum — an array of length ncols, containing the numbers of the columns that are to be changed. plot twist: column numbers start at 1 ⭐
• Datum * values — an array of length ncols, containing the new values for the specified columns.
• const char * nulls — an array of length ncols, describing which new values are null. ok this one needs a lil explanation:
  • if nulls is NULL then SPI_modifytuple assumes that no new values are null.
  • otherwise, each entry of the nulls array should be ' ' if the corresponding new value is non-null, or 'n' if the corresponding new value is null. (in that null case, the actual value in the corresponding values entry doesn't matter — she's not even looking 💀)
  • and note: nulls is not a text string, just an array. it does not need a '\0' terminator. no cap 🧚

👑 RETURN VALUE 👑

new row with modifications, allocated in the upper executor context 🎉 — or NULL on error (check SPI_result for the error indication, she'll tell you what went wrong 💜).

On error, SPI_result is set as follows:

• SPI_ERROR_ARGUMENT — if rel is NULL, or if row is NULL, or if ncols is less than or equal to 0, or if colnum is NULL, or if values is NULL. basically somebody passed you nothing, bestie 😭
• SPI_ERROR_NOATTRIBUTE — if colnum contains an invalid column number (less than or equal to 0, or greater than the number of columns in row). remember, columns start at 1 🔥
• SPI_ERROR_UNCONNECTED — if SPI is not active. no SPI, no slay 🙈

---

and that's the whole page, periodt 💅✨

this lil masterpiece comes to you courtesy of the PostgreSQL 16.15 docs, dated 2026 — see you in the next manpage, bestie 🫶🎀🦋💖⭐