begriffs open source - ai-pg/blob - full-docs/txt/spi.txt

   1
   2 Chapter 45. Server Programming Interface
   3
   4    Table of Contents
   5
   6    45.1. Interface Functions
   7
   8         SPI_connect — connect a C function to the SPI manager
   9         SPI_finish — disconnect a C function from the SPI manager
  10         SPI_execute — execute a command
  11         SPI_exec — execute a read/write command
  12         SPI_execute_extended — execute a command with out-of-line
  13                 parameters
  14
  15         SPI_execute_with_args — execute a command with out-of-line
  16                 parameters
  17
  18         SPI_prepare — prepare a statement, without executing it yet
  19         SPI_prepare_cursor — prepare a statement, without executing it yet
  20         SPI_prepare_extended — prepare a statement, without executing it
  21                 yet
  22
  23         SPI_prepare_params — prepare a statement, without executing it yet
  24         SPI_getargcount — return the number of arguments needed by a
  25                 statement prepared by SPI_prepare
  26
  27         SPI_getargtypeid — return the data type OID for an argument of a
  28                 statement prepared by SPI_prepare
  29
  30         SPI_is_cursor_plan — return true if a statement prepared by
  31                 SPI_prepare can be used with SPI_cursor_open
  32
  33         SPI_execute_plan — execute a statement prepared by SPI_prepare
  34         SPI_execute_plan_extended — execute a statement prepared by
  35                 SPI_prepare
  36
  37         SPI_execute_plan_with_paramlist — execute a statement prepared by
  38                 SPI_prepare
  39
  40         SPI_execp — execute a statement in read/write mode
  41         SPI_cursor_open — set up a cursor using a statement created with
  42                 SPI_prepare
  43
  44         SPI_cursor_open_with_args — set up a cursor using a query and
  45                 parameters
  46
  47         SPI_cursor_open_with_paramlist — set up a cursor using parameters
  48         SPI_cursor_parse_open — set up a cursor using a query string and
  49                 parameters
  50
  51         SPI_cursor_find — find an existing cursor by name
  52         SPI_cursor_fetch — fetch some rows from a cursor
  53         SPI_cursor_move — move a cursor
  54         SPI_scroll_cursor_fetch — fetch some rows from a cursor
  55         SPI_scroll_cursor_move — move a cursor
  56         SPI_cursor_close — close a cursor
  57         SPI_keepplan — save a prepared statement
  58         SPI_saveplan — save a prepared statement
  59         SPI_register_relation — make an ephemeral named relation available
  60                 by name in SPI queries
  61
  62         SPI_unregister_relation — remove an ephemeral named relation from
  63                 the registry
  64
  65         SPI_register_trigger_data — make ephemeral trigger data available
  66                 in SPI queries
  67
  68    45.2. Interface Support Functions
  69
  70         SPI_fname — determine the column name for the specified column
  71                 number
  72
  73         SPI_fnumber — determine the column number for the specified column
  74                 name
  75
  76         SPI_getvalue — return the string value of the specified column
  77         SPI_getbinval — return the binary value of the specified column
  78         SPI_gettype — return the data type name of the specified column
  79         SPI_gettypeid — return the data type OID of the specified column
  80         SPI_getrelname — return the name of the specified relation
  81         SPI_getnspname — return the namespace of the specified relation
  82         SPI_result_code_string — return error code as string
  83
  84    45.3. Memory Management
  85
  86         SPI_palloc — allocate memory in the upper executor context
  87         SPI_repalloc — reallocate memory in the upper executor context
  88         SPI_pfree — free memory in the upper executor context
  89         SPI_copytuple — make a copy of a row in the upper executor context
  90         SPI_returntuple — prepare to return a tuple as a Datum
  91         SPI_modifytuple — create a row by replacing selected fields of a
  92                 given row
  93
  94         SPI_freetuple — free a row allocated in the upper executor context
  95         SPI_freetuptable — free a row set created by SPI_execute or a
  96                 similar function
  97
  98         SPI_freeplan — free a previously saved prepared statement
  99
 100    45.4. Transaction Management
 101
 102         SPI_commit — commit the current transaction
 103         SPI_rollback — abort the current transaction
 104         SPI_start_transaction — obsolete function
 105
 106    45.5. Visibility of Data Changes
 107    45.6. Examples
 108
 109    The Server Programming Interface (SPI) gives writers of user-defined C
 110    functions the ability to run SQL commands inside their functions or
 111    procedures. SPI is a set of interface functions to simplify access to
 112    the parser, planner, and executor. SPI also does some memory
 113    management.
 114
 115 Note
 116
 117    The available procedural languages provide various means to execute SQL
 118    commands from functions. Most of these facilities are based on SPI, so
 119    this documentation might be of use for users of those languages as
 120    well.
 121
 122    Note that if a command invoked via SPI fails, then control will not be
 123    returned to your C function. Rather, the transaction or subtransaction
 124    in which your C function executes will be rolled back. (This might seem
 125    surprising given that the SPI functions mostly have documented
 126    error-return conventions. Those conventions only apply for errors
 127    detected within the SPI functions themselves, however.) It is possible
 128    to recover control after an error by establishing your own
 129    subtransaction surrounding SPI calls that might fail.
 130
 131    SPI functions return a nonnegative result on success (either via a
 132    returned integer value or in the global variable SPI_result, as
 133    described below). On error, a negative result or NULL will be returned.
 134
 135    Source code files that use SPI must include the header file
 136    executor/spi.h.