Section 3: library functions
SPI_scroll_cursor_move – move a cursor Synopsis void SPI_scroll_cursor_move(Portal portal, FetchDirection direction, long count) Description SPI_scroll_cursor_move skips over some number of rows in a cursor. This is equivalent to the SQL command MOVE. Arguments Portal portal portal containing the cursor FetchDirection direction one of FETCH_FORWARD, FETCH_BACKWARD, FETCH_ABSOLUTE or FETCH_RELATIVE long count number of rows to move…
SPI_scroll_cursor_fetch – fetch some rows from a cursor Synopsis void SPI_scroll_cursor_fetch(Portal portal, FetchDirection direction, long count) Description SPI_scroll_cursor_fetch fetches some rows from a cursor. This is equivalent to the SQL command FETCH. Arguments Portal portal portal containing the cursor FetchDirection direction one of FETCH_FORWARD, FETCH_BACKWARD, FETCH_ABSOLUTE or FETCH_RELATIVE long count number of rows to fetch…
SPI_saveplan – save a prepared statement Synopsis SPIPlanPtr SPI_saveplan(SPIPlanPtr plan) Description SPI_saveplan copies a passed statement (prepared by SPI_prepare) into memory that will not be freed by SPI_finish nor by the transaction manager, and returns a pointer to the copied statement. This gives you the ability to reuse prepared statements in the subsequent invocations of…
SPI_returntuple – prepare to return a tuple as a Datum Synopsis HeapTupleHeader SPI_returntuple(HeapTuple row, TupleDesc rowdesc) Description 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. Note that this…
SPI_repalloc – reallocate memory in the upper executor context Synopsis void * SPI_repalloc(void * pointer, Size size) Description SPI_repalloc changes the size of a memory segment previously allocated using SPI_palloc. This function is no longer different from plain repalloc. It’s kept just for backward compatibility of existing code. Arguments void * pointer pointer to existing…
SPI_push – push SPI stack to allow recursive SPI usage Synopsis void SPI_push(void) Description SPI_push should be called before executing another procedure that might itself wish to use SPI. After SPI_push, SPI is no longer in a “connected” state, and SPI function calls will be rejected unless a fresh SPI_connect is done. This ensures a…
SPI_prepare_params – prepare a statement, without executing it yet Synopsis SPIPlanPtr SPI_prepare_params(const char * command, ParserSetupHook parserSetup, void * parserSetupArg, int cursorOptions) Description SPI_prepare_params creates and returns a prepared statement for the specified command, but doesn’t execute the command. This function is equivalent to SPI_prepare_cursor, with the addition that the caller can specify parser hook…
SPI_prepare_cursor – prepare a statement, without executing it yet Synopsis SPIPlanPtr SPI_prepare_cursor(const char * command, int nargs, Oid * argtypes, int cursorOptions) Description SPI_prepare_cursor is identical to SPI_prepare, except that it also allows specification of the planner’s “cursor options” parameter. This is a bit mask having the values shown in nodes/parsenodes.h for the options field…
SPI_prepare – prepare a statement, without executing it yet Synopsis SPIPlanPtr SPI_prepare(const char * command, int nargs, Oid * argtypes) Description SPI_prepare creates and returns a prepared statement for the specified command, but doesn’t execute the command. The prepared statement can later be executed repeatedly using SPI_execute_plan. When the same or a similar command is…
SPI_pop – pop SPI stack to return from recursive SPI usage Synopsis void SPI_pop(void) Description SPI_pop pops the previous environment from the SPI call stack. See SPI_push.
SPI_pfree – free memory in the upper executor context Synopsis void SPI_pfree(void * pointer) Description SPI_pfree frees memory previously allocated using SPI_palloc or SPI_repalloc. This function is no longer different from plain pfree. It’s kept just for backward compatibility of existing code. Arguments void * pointer pointer to existing storage to free
SPI_palloc – allocate memory in the upper executor context Synopsis void * SPI_palloc(Size size) Description SPI_palloc allocates memory in the upper executor context. Arguments Size size size in bytes of storage to allocate Return Value pointer to new storage space of the specified size
SPI_modifytuple – create a row by replacing selected fields of a given row Synopsis HeapTuple SPI_modifytuple(Relation rel, HeapTuple row, int ncols, int * colnum, Datum * values, const char * nulls) Description SPI_modifytuple creates a new row by substituting new values for selected columns, copying the original row’s columns at other positions. The input row…
SPI_keepplan – save a prepared statement Synopsis int SPI_keepplan(SPIPlanPtr plan) Description SPI_keepplan saves a passed statement (prepared by SPI_prepare) so that it will not be freed by SPI_finish nor by the transaction manager. This gives you the ability to reuse prepared statements in the subsequent invocations of your procedure in the current session. Arguments SPIPlanPtr…
SPI_is_cursor_plan – return true if a statement prepared by SPI_prepare can be used with SPI_cursor_open Synopsis bool SPI_is_cursor_plan(SPIPlanPtr plan) Description SPI_is_cursor_plan returns true if a statement prepared by SPI_prepare can be passed as an argument to SPI_cursor_open, or false if that is not the case. The criteria are that the plan represents one single command…
SPI_getvalue – return the string value of the specified column Synopsis char * SPI_getvalue(HeapTuple row, TupleDesc rowdesc, int colnumber) Description SPI_getvalue returns the string representation of the value of the specified column. The result is returned in memory allocated using palloc. (You can use pfree to release the memory when you don’t need it anymore.)…
SPI_gettypeid – return the data type OID of the specified column Synopsis Oid SPI_gettypeid(TupleDesc rowdesc, int colnumber) Description SPI_gettypeid returns the OID of the data type of the specified column. Arguments TupleDesc rowdesc input row description int colnumber column number (count starts at 1) Return Value The OID of the data type of the specified…
SPI_gettype – return the data type name of the specified column Synopsis char * SPI_gettype(TupleDesc rowdesc, int colnumber) Description SPI_gettype returns a copy of the data type name of the specified column. (You can use pfree to release the copy of the name when you don’t need it anymore.) Arguments TupleDesc rowdesc input row description…
SPI_getrelname – return the name of the specified relation Synopsis char * SPI_getrelname(Relation rel) Description SPI_getrelname returns a copy of the name of the specified relation. (You can use pfree to release the copy of the name when you don’t need it anymore.) Arguments Relation rel input relation Return Value The name of the specified…
SPI_getnspname – return the namespace of the specified relation Synopsis char * SPI_getnspname(Relation rel) Description SPI_getnspname returns a copy of the name of the namespace that the specified Relation belongs to. This is equivalent to the relation’s schema. You should pfree the return value of this function when you are finished with it. Arguments Relation…