The Server Programming Interface
(SPI) gives writers of
user-defined C functions the
ability to run SQL commands
inside their functions. SPI is
a set of interface functions to simplify access to the parser,
planner, optimizer, and executor. SPI also does some memory management.

Note: The available procedural languages provide
various means to execute SQL commands from procedures. Most
of these facilities are based on SPI, so this documentation
might be of use for users of those languages as well.

To avoid misunderstanding we'll use the term "function" when we speak of SPI interface functions and "procedure" for a user-defined C-function that is
using SPI.

Note that if a command invoked via SPI fails, then control
will not be returned to your procedure. Rather, the transaction
or subtransaction in which your procedure executes will be rolled
back. (This may 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. This is not currently
documented because the mechanisms required are still in flux.

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.