SPI_RETURNTUPLE(3)

✨ SPI_RETURNTUPLE(3) ✨

okay so bestie, welcome to SPI_RETURNTUPLE(3) — that’s the manual name, and this is the PostgreSQL 13.23 Documentation version. we’re about to make a tuple-returning Datum moment happen 💅

🌸 NAME 🌸

SPI_returntuple — prepare to return a tuple as a Datum. simple, iconic, does what it says 🎀

🦋 SYNOPSIS 🦋

HeapTupleHeader SPI_returntuple(HeapTuple row, TupleDesc rowdesc)

💖 DESCRIPTION 💖

SPI_returntuple makes a copy of a row in the upper executor context, and returns it in the form of a row type Datum. the returned pointer only needs to be converted to Datum via PointerGetDatum before returning. slay ✨

this function can only be used while connected to SPI. otherwise, it returns NULL and sets SPI_result to SPI_ERROR_UNCONNECTED. so yeah, no SPI connection = no tuple, bestie 😭

note that this should be used for functions that are declared to return composite types. it is not used for triggers; for returning a modified row in a trigger, use SPI_copytuple instead. important vibe check 🫶

💅 ARGUMENTS 💅

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

👑 RETURN VALUE 👑

HeapTupleHeader pointing to the copied row, or NULL on error. for an error indication, see SPI_result. that’s the whole tea 💖

okay that’s the page, bestie 🫶 stay connected to SPI, convert with PointerGetDatum, and don’t use this for triggers — use SPI_copytuple, periodt. xoxo, PostgreSQL 13.23, 2025 🎀💖