SPI_RETURNTUPLE(3)

✨ bestie's guide to SPI_RETURNTUPLE(3) — PostgreSQL 14.24 Documentation ✨

okay so you're looking at the SPI_RETURNTUPLE(3) page from the PostgreSQL 14.24 docs, and it's giving tiny but crucial C API moment. No cap, we're keeping every detail, every caveat, every crumb. 💅

---

🎀 NAME 🎀

• SPI_returntuple — prepare to return a tuple as a Datum.

---

🌈 SYNOPSIS 🌈

HeapTupleHeader SPI_returntuple(HeapTuple row, TupleDesc rowdesc)

---

💅 DESCRIPTION 💅

So here's the vibe: SPI_returntuple makes a copy of a row in the upper executor context, returning it in the form of a row type Datum. The returned pointer need only be converted to Datum via PointerGetDatum before returning. That's it. That's the whole assignment. ✨

This function can only be used while connected to SPI. Otherwise, it returns NULL and sets SPI_result to SPI_ERROR_UNCONNECTED. Vibe check: connected or it ghosts you. 😭

🫶 Note that this should be used for functions that are declared to return composite types. It is not used for triggers; use SPI_copytuple for returning a modified row in a trigger. Periodt.

---

🦋 ARGUMENTS 🦋

• HeapTuple row — row to be copied.
• TupleDesc rowdesc — descriptor for row (pass the same descriptor each time for most effective caching).

---

🔥 RETURN VALUE 🔥

HeapTupleHeader pointing to copied row, or NULL on error (see SPI_result for an error indication), bestie.

---

💖 That's the whole page, babe — brought to you by PostgreSQL 14.24, dated 2026, and filed under SPI_RETURNTUPLE(3). Mwah 💋