Глава 45. Интерфейс программирования сервера
Содержание
- 45.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
- SPI_finish — отключить функцию на C от менеджера SPI
- SPI_connect — подключить функцию на C к менеджеру SPI
- 45.2. Вспомогательные интерфейсные функции
- SPI_fname — определить имя столбца с заданным номером
- SPI_fnumber — определить номер столбца с заданным именем
- SPI_getvalue — получить строковое значение указанного столбца
- SPI_getbinval — получить двоичное значение указанного столбца
- SPI_gettype — получить имя типа данных указанного столбца
- SPI_gettypeid — получить OID типа данных указанного столбца
- SPI_getrelname — возвращает имя указанного отношения
- SPI_getnspname — возвращает пространство имён указанного отношения
- SPI_result_code_string — возвращает код ошибки в виде строки
- SPI_fnumber — определить номер столбца с заданным именем
- SPI_fname — определить имя столбца с заданным номером
- 45.3. Управление памятью
- SPI_palloc — выделить память в верхнем контексте исполнителя
- SPI_repalloc — поменять блок памяти в верхнем контексте исполнителя
- SPI_pfree — освободить память в верхнем контексте исполнителя
- SPI_copytuple — скопировать строку в верхнем контексте исполнителя
- SPI_returntuple — подготовить строку для возврата в виде Datum
- SPI_modifytuple — создать строку, заменяя отдельные поля в данной
- SPI_freetuple — освободить строку, размещённую в верхнем контексте исполнителя
- SPI_freetuptable — освободить набор строк, созданный
SPI_executeили подобной функцией- SPI_freeplan — освободить ранее сохранённый подготовленный оператор
- SPI_repalloc — поменять блок памяти в верхнем контексте исполнителя
- SPI_palloc — выделить память в верхнем контексте исполнителя
- 45.4. Управление транзакциями
- SPI_commit — зафиксировать текущую транзакцию
- SPI_rollback — прервать текущую транзакцию
- SPI_start_transaction — устаревшая функция
- SPI_rollback — прервать текущую транзакцию
- SPI_commit — зафиксировать текущую транзакцию
- 45.5. Видимость изменений в данных
- 45.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 45. Server Programming Interface
Table of Contents
- 45.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
trueif a statement prepared bySPI_preparecan be used withSPI_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
- SPI_finish — disconnect a C function from the SPI manager
- SPI_connect — connect a C function to the SPI manager
- 45.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
- SPI_fnumber — determine the column number for the specified column name
- SPI_fname — determine the column name for the specified column number
- 45.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_executeor a similar function- SPI_freeplan — free a previously saved prepared statement
- SPI_repalloc — reallocate memory in the upper executor context
- SPI_palloc — allocate memory in the upper executor context
- 45.4. Transaction Management
- SPI_commit — commit the current transaction
- SPI_rollback — abort the current transaction
- SPI_start_transaction — obsolete function
- SPI_rollback — abort the current transaction
- SPI_commit — commit the current transaction
- 45.5. Visibility of Data Changes
- 45.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.