SPI_CURSOR_OPEN(3)

SPI_CURSOR_OPEN(3) 💅

okay so this is the PostgreSQL 13.23 Documentation page for SPI_cursor_open, manual section 3, and it's literally the glow-up for turning a prepared statement into a cursor. no cap. ✨

💖 NAME 💖

SPI_cursor_open — set 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 🎀

SPI_cursor_open sets up a cursor — and internally that cursor is a portal — that will execute a statement you already prepared with SPI_prepare. The parameters do the same jobs as the corresponding parameters to SPI_execute_plan, iykyk.

Using a cursor instead of just executing the statement directly gives you two big benefits, bestie:

1. You can grab the result rows a few at a time, so queries that return a ton of rows don't cause a memory overrun. literally saving your RAM's life. 🫶
2. A portal can outlive the current C function — it can actually live until the end of the current transaction. So if you return the portal name to the C function's caller, you've got a way to hand back a row set as the result. main character portal behavior. 👑

The parameter data you pass in gets copied into the cursor's portal, so you can free it while the cursor still exists. no stress. 🌸

🌈 ARGUMENTS 🌈

• const char * name — the name for the portal, or NULL to let the system pick a name for you. choose-your-own-adventure but the system can choose too.
• SPIPlanPtr plan — the prepared statement, returned by SPI_prepare. that's the whole point.
• Datum * values — an array of actual parameter values. It must have the same length as the statement's number of arguments. match made in heaven, but like, length-wise. 💜
• const char * nulls — an array describing which parameters are null. It also 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 that null case, the actual value in the corresponding values entry doesn't matter.) Also note: nulls is not a text string, it's just an array, so it does not need a '\0' terminator. bestie please don't add one. it's giving char array not string. 😭
• bool read_only — true for read-only execution.

👑 RETURN VALUE 👑

It returns a pointer to the portal containing the cursor. Heads up: there's no error return convention here — any error will be reported via elog. so like, don't go looking for a fancy error code, mmkay? 💀

xoxo, this page is from PostgreSQL 13.23, dated 2025 — stay slay and may your portals outlive your functions 💅✨