Chapter 46. Server Programming Interface

Chapter 46. Server Programming Interface
Prev	Up	Part V. Server Programming	Home	Next

Table of Contents

46.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_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_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_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_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

46.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

46.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

46.4. Transaction Management

SPI_commit — commit the current transaction
SPI_rollback — abort the current transaction
SPI_start_transaction — start a new transaction

46.5. Visibility of Data Changes

46.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. +

Prev	Up	Next
45.11. Environment Variables	Home	46.1. Interface Functions