Глава 49. Интерфейс программирования сервера

Содержание

49.1. Интерфейсные функции
SPI_connect — подключить функцию на C к менеджеру SPI
SPI_finish — отключить функцию на C от менеджера SPI
SPI_execute — выполнить команду
SPI_exec — выполнить команду чтения/записи
SPI_execute_extended — выполнить команду с выделенными параметрами
SPI_execute_with_args — выполнить команду с выделенными параметрами
SPI_prepare — подготовить оператор, но пока не выполнять его
SPI_prepare_cursor — подготовить оператор, но пока не выполнять его
SPI_prepare_extended — подготовить оператор, но пока не выполнять его
SPI_prepare_params — подготовить оператор, но пока не выполнять его
SPI_getargcount — получить число аргументов, требующихся оператору, подготовленному функцией SPI_prepare
SPI_getargtypeid — получить OID типа аргумента для оператора, подготовленного функцией SPI_prepare
SPI_is_cursor_plan — выдать true, если оператор, подготовленный функцией SPI_prepare, можно использовать с SPI_cursor_open
SPI_execute_plan — выполнить оператор, подготовленный функцией SPI_prepare
SPI_execute_plan_extended — выполнить оператор, подготовленный функцией SPI_prepare
SPI_execute_plan_with_paramlist — выполнить оператор, подготовленный функцией SPI_prepare
SPI_execp — выполнить оператор в режиме чтения/записи
SPI_cursor_open — открыть курсор для оператора, созданного функцией SPI_prepare
SPI_cursor_open_with_args — открывает курсор для запроса с параметрами
SPI_cursor_open_with_paramlist — открыть курсор с параметрами
SPI_cursor_parse_open — открывает курсор для строки запроса и набора параметров
SPI_cursor_find — найти существующий курсор по имени
SPI_cursor_fetch — выбрать строки через курсор
SPI_cursor_move — переместить курсор
SPI_scroll_cursor_fetch — выбрать строки через курсор
SPI_scroll_cursor_move — переместить курсор
SPI_cursor_close — закрыть курсор
SPI_keepplan — сохранить подготовленный оператор
SPI_saveplan — сохранить подготовленный оператор
SPI_register_relation — сделать эфемерное именованное отношение доступным по имени в запросах SPI
SPI_unregister_relation — удалить эфемерное именованное отношение из реестра
SPI_register_trigger_data — сделать эфемерные данные триггера доступными в запросах SPI
49.2. Вспомогательные интерфейсные функции
SPI_fname — определить имя столбца с заданным номером
SPI_fnumber — определить номер столбца с заданным именем
SPI_getvalue — получить строковое значение указанного столбца
SPI_getbinval — получить двоичное значение указанного столбца
SPI_gettype — получить имя типа данных указанного столбца
SPI_gettypeid — получить OID типа данных указанного столбца
SPI_getrelname — возвращает имя указанного отношения
SPI_getnspname — возвращает пространство имён указанного отношения
SPI_result_code_string — возвращает код ошибки в виде строки
49.3. Управление памятью
SPI_palloc — выделить память в верхнем контексте исполнителя
SPI_repalloc — поменять блок памяти в верхнем контексте исполнителя
SPI_pfree — освободить память в верхнем контексте исполнителя
SPI_copytuple — скопировать строку в верхнем контексте исполнителя
SPI_returntuple — подготовить строку для возврата в виде Datum
SPI_modifytuple — создать строку, заменяя отдельные поля в данной
SPI_freetuple — освободить строку, размещённую в верхнем контексте исполнителя
SPI_freetuptable — освободить набор строк, созданный SPI_execute или подобной функцией
SPI_freeplan — освободить ранее сохранённый подготовленный оператор
49.4. Управление транзакциями
SPI_commit — зафиксировать текущую транзакцию
SPI_rollback — прервать текущую транзакцию
SPI_start_transaction — устаревшая функция
49.5. Видимость изменений в данных
49.6. Примеры

Интерфейс программирования сервера (SPI, Server Programming Interface) даёт разработчикам пользовательских функций на C возможность запускать команды SQL из своих функций или процедур. SPI представляет собой набор интерфейсных функций, упрощающих доступ к анализатору, планировщику и исполнителю запросов. В SPI есть также функции для управления памятью.

Примечание

Доступные процедурные языки предоставляют различные средства для выполнения SQL-команд из функций. Большинство этих средств основаны на SPI, так что эта документация будет полезна и тем, кто использует эти языки.

Учтите, что если команда, вызванная через SPI, прерывается ошибкой, управление не возвращается в вашу функцию на C. Вместо этого происходит откат транзакции или подтранзакции, из которой вызывалась ваша функция. (Это может показаться удивительным с учётом того, что для большинства функций SPI описаны соглашения по возврату ошибок. Однако эти соглашения применимы только к ошибкам, выявляемым в самих функциях SPI.) Получить управление после ошибки можно, только организовав собственную подтранзакцию, окружающую вызовы SPI, в которых возможна ошибка.

Функции SPI выдают неотрицательный результат в случае успеха (либо через возвращаемое целочисленное значение, либо в глобальной переменной SPI_result, как описано ниже). В случае ошибки выдаётся отрицательный результат или NULL.

Файлы исходного кода, использующие SPI, должны включать заголовочный файл executor/spi.h.

Chapter 49. Server Programming Interface

Table of Contents

49.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
49.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
49.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
49.4. Transaction Management
SPI_commit — commit the current transaction
SPI_rollback — abort the current transaction
SPI_start_transaction — obsolete function
49.5. Visibility of Data Changes
49.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.

FAQ