SPI_RETURNTUPLE(3)

💖 SPI_RETURNTUPLE(3) 💖

okay bestie, so this is a page from the PostgreSQL 18.6 Documentation, and today's main character is SPI_returntuple — the girl who preps your tuple so it can go out into the world as a Datum. slay. let's get into it. 🎀

---

✨ NAME ✨

SPI_returntuple — get ready to return a tuple as a Datum 💅

---

🌸 SYNOPSIS 🌸

HeapTupleHeader SPI_returntuple(HeapTuple row, TupleDesc rowdesc)

---

🦋 DESCRIPTION 🦋

so basically, SPI_returntuple makes a copy of a row over in the upper executor context, and hands it back to you in the form of a row type Datum. the returned pointer? you literally only need to convert it to Datum via PointerGetDatum before returning it. that's it. that's the whole vibe. ✨

🚨 important: this function can only be used while you're connected to SPI. if you're not connected, it returns NULL and sets SPI_result to SPI_ERROR_UNCONNECTED. so, like, vibe check first, okay? 💀

also, heads up: this one is meant for functions that are declared to return composite types. it is not used for triggers — if you're returning a modified row in a trigger, use SPI_copytuple instead. different girl, different job, no cap. 👑

---

🎀 ARGUMENTS 🎀

• HeapTuple row — the row you want copied. just, like, hand her the row. 🫶
• TupleDesc rowdesc — the descriptor for the row. and fr fr, pass the same descriptor every time if you want the most effective caching. consistency is iconic. ⭐

---

💜 RETURN VALUE 💜

a HeapTupleHeader pointing to the copied row — or NULL if something went wrong (peep SPI_result for the error indication, she'll tell you what happened). 😭

---

🌈 SEE ALSO 🌈

okay so the original page didn't list any SEE ALSO references — nothing else to link, bestie, that's the whole list. 💖

---

and that's the page!! this one came from the PostgreSQL 18.6 docs, dated 2026, filed under SPI_RETURNTUPLE(3). go forth and return your tuples, queen. 👑✨🦋