SPI_CURSOR_OPEN(3)

✨ SPI_CURSOR_OPEN ✨

okay bestie, gather round, because we're about to talk about SPI_cursor_open — and no, it's not a PostgreSQL 18.6 Documentation thing you can skip, this is the one that sets up a cursor using a statement created with SPI_prepare. 💅

---

🌸 SYNOPSIS 🌸

Portal SPI_cursor_open(const char * name, SPIPlanPtr plan,
                       Datum * values, const char * nulls,
                       bool read_only)

---

💖 DESCRIPTION 💖

so SPI_cursor_open sets up a cursor (which internally? a portal, iykyk) that will execute a statement you already prepared with SPI_prepare. and the parameters? they have the same meanings as the corresponding parameters to SPI_execute_plan. like, same energy, same rules, no cap. 🫶

now why would you use a cursor instead of just executing the statement directly?? two benefits, and both of them are lowkey iconic:

1. the result rows can be retrieved a few at a time — which means you avoid memory overrun for queries that return a lot of rows. your RAM stays unbothered. 💀
2. a portal can outlive the current C function — it can, in fact, live all the way to the end of the current transaction. main character longevity fr fr. and returning the portal name to the C function's caller gives you a way of returning a row set as a result. 🎀

also, important: the passed-in parameter data will be copied into the cursor's portal, so you can free it while the cursor still exists. she doesn't need your original array anymore, she has her own. ✨

---

🦋 ARGUMENTS 🦋

• const char * name — the name for the portal, or NULL to let the system select a name. let the system cook. 👑
• SPIPlanPtr plan — the prepared statement (the one returned by SPI_prepare). you know her.
• Datum * values — an array of actual parameter values. must have the same length as the statement's number of arguments. no short arrays, no long arrays, we match. ⭐
• const char * nulls — an array describing which parameters are null. must have the same length as the statement's number of arguments.

if nulls is NULL then SPI_cursor_open assumes that no parameters are null. otherwise, each entry of the nulls array should be ' ' if the corresponding parameter value is non-null, or 'n' if the corresponding parameter value is null. (in the latter case, the actual value in the corresponding values entry doesn't matter — she's not even looking at it. 🙈) and note: nulls is not a text string, just an array — it does not need a '\0' terminator. this is not a string bestie, do not terminate her. 💜

• bool read_only — true for read-only execution.

---

🌈 RETURN VALUE 🌈

a pointer to the portal containing the cursor. 🎉

⚠️ heads up though: there is no error return convention — any error will be reported via elog. so like, don't go checking for a NULL return and thinking you're safe, because that's not the vibe here. errors come through elog, periodt.

---

and that's the whole page, bestie!! every option, every argument, every little '\0' caveat — all accounted for. stay slaying those portals 🧚

💖 this has been PostgreSQL 18.6 documentation, dated 2026, signing off — mwah 💖