Chapter 45. Server Programming Interface Table of Contents 45.1. Interface Functions SPI_connect — connect a C function to the SPI manager SPI_finish — disconnect a C function from the SPI manager SPI_execute — execute a command SPI_exec — execute a read/write command SPI_execute_extended — execute a command with out-of-line parameters SPI_execute_with_args — execute a command with out-of-line parameters SPI_prepare — prepare a statement, without executing it yet SPI_prepare_cursor — prepare a statement, without executing it yet SPI_prepare_extended — prepare a statement, without executing it yet SPI_prepare_params — prepare a statement, without executing it yet SPI_getargcount — return the number of arguments needed by a statement prepared by SPI_prepare SPI_getargtypeid — return the data type OID for an argument of a statement prepared by SPI_prepare SPI_is_cursor_plan — return true if a statement prepared by SPI_prepare can be used with SPI_cursor_open SPI_execute_plan — execute a statement prepared by SPI_prepare SPI_execute_plan_extended — execute a statement prepared by SPI_prepare SPI_execute_plan_with_paramlist — execute a statement prepared by SPI_prepare SPI_execp — execute a statement in read/write mode SPI_cursor_open — set up a cursor using a statement created with SPI_prepare SPI_cursor_open_with_args — set up a cursor using a query and parameters SPI_cursor_open_with_paramlist — set up a cursor using parameters SPI_cursor_parse_open — set up a cursor using a query string and parameters SPI_cursor_find — find an existing cursor by name SPI_cursor_fetch — fetch some rows from a cursor SPI_cursor_move — move a cursor SPI_scroll_cursor_fetch — fetch some rows from a cursor SPI_scroll_cursor_move — move a cursor SPI_cursor_close — close a cursor SPI_keepplan — save a prepared statement SPI_saveplan — save a prepared statement SPI_register_relation — make an ephemeral named relation available by name in SPI queries SPI_unregister_relation — remove an ephemeral named relation from the registry SPI_register_trigger_data — make ephemeral trigger data available in SPI queries 45.2. Interface Support Functions SPI_fname — determine the column name for the specified column number SPI_fnumber — determine the column number for the specified column name SPI_getvalue — return the string value of the specified column SPI_getbinval — return the binary value of the specified column SPI_gettype — return the data type name of the specified column SPI_gettypeid — return the data type OID of the specified column SPI_getrelname — return the name of the specified relation SPI_getnspname — return the namespace of the specified relation SPI_result_code_string — return error code as string 45.3. Memory Management SPI_palloc — allocate memory in the upper executor context SPI_repalloc — reallocate memory in the upper executor context SPI_pfree — free memory in the upper executor context SPI_copytuple — make a copy of a row in the upper executor context SPI_returntuple — prepare to return a tuple as a Datum SPI_modifytuple — create a row by replacing selected fields of a given row SPI_freetuple — free a row allocated in the upper executor context SPI_freetuptable — free a row set created by SPI_execute or a similar function SPI_freeplan — free a previously saved prepared statement 45.4. Transaction Management SPI_commit — commit the current transaction SPI_rollback — abort the current transaction SPI_start_transaction — obsolete function 45.5. Visibility of Data Changes 45.6. Examples The Server Programming Interface (SPI) gives writers of user-defined C functions the ability to run SQL commands inside their functions or procedures. SPI is a set of interface functions to simplify access to the parser, planner, and executor. SPI also does some memory management. Note The available procedural languages provide various means to execute SQL commands from functions. Most of these facilities are based on SPI, so this documentation might be of use for users of those languages as well. Note that if a command invoked via SPI fails, then control will not be returned to your C function. Rather, the transaction or subtransaction in which your C function executes will be rolled back. (This might seem surprising given that the SPI functions mostly have documented error-return conventions. Those conventions only apply for errors detected within the SPI functions themselves, however.) It is possible to recover control after an error by establishing your own subtransaction surrounding SPI calls that might fail. SPI functions return a nonnegative result on success (either via a returned integer value or in the global variable SPI_result, as described below). On error, a negative result or NULL will be returned. Source code files that use SPI must include the header file executor/spi.h.