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

Содержание
44.1. Интерфейсные функции
SPI_connect -- подключить процедуру к менеджеру SPI
SPI_finish -- отключить процедуру от менеджера SPI
SPI_push -- поднять стек SPI для входа в рекурсивное использование SPI
SPI_pop -- опустить стек SPI для выхода из рекурсивного использования SPI
SPI_execute -- выполнить команду
SPI_exec -- выполнить команду чтения/записи
SPI_execute_with_args -- выполнить команду с выделенными параметрами
SPI_prepare -- подготовить оператор, но пока не выполнять его
SPI_prepare_cursor -- подготовить оператор, но пока не выполнять его
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_with_paramlist -- выполнить оператор, подготовленный функцией SPI_prepare
SPI_execp -- выполнить оператор в режиме чтения/записи
SPI_cursor_open -- открыть курсор для оператора, созданного функцией SPI_prepare
SPI_cursor_open_with_args -- открывает курсор для запроса с параметрами
SPI_cursor_open_with_paramlist -- открыть курсор с параметрами
SPI_cursor_find -- найти существующий курсор по имени
SPI_cursor_fetch -- выбрать строки через курсор
SPI_cursor_move -- переместить курсор
SPI_scroll_cursor_fetch -- выбрать строки через курсор
SPI_scroll_cursor_move -- переместить курсор
SPI_cursor_close -- закрыть курсор
SPI_keepplan -- сохранить подготовленный оператор
SPI_saveplan -- сохранить подготовленный оператор
44.2. Вспомогательные интерфейсные функции
SPI_fname -- определить имя колонки с заданным номером
SPI_fnumber -- определить номер колонки с заданным именем
SPI_getvalue -- получить строковое значение указанной колонки
SPI_getbinval -- получить двоичное значение указанной колонки
SPI_gettype -- получить имя типа данных указанной колонки
SPI_gettypeid -- получить OID типа данных указанной колонки
SPI_getrelname -- возвращает имя указанного отношения
SPI_getnspname -- возвращает пространство имён указанного отношения
44.3. Управление памятью
SPI_palloc -- выделить память в верхнем контексте исполнителя
SPI_repalloc -- поменять блок памяти в верхнем контексте исполнителя
SPI_pfree -- освободить память в верхнем контексте исполнителя
SPI_copytuple -- скопировать строку в верхнем контексте исполнителя
SPI_returntuple -- подготовить строку для возврата в виде Datum
SPI_modifytuple -- создать строку, заменяя отдельные поля в данной
SPI_freetuple -- освободить строку, размещённую в верхнем контексте исполнителя
SPI_freetuptable -- освободить набор строк, созданный SPI_execute или подобной функцией
SPI_freeplan -- освободить ранее сохранённый подготовленный оператор
44.4. Видимость изменений в данных
44.5. Примеры

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

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

Во избежание недопонимания мы будем употреблять слово "функция", говоря о функциях SPI, и слово "процедура", говоря о пользовательских функциях, написанных на C, и использующих SPI.

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

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

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