SPI_execute
SPI_execute — выполнить команду
Синтаксис
int SPI_execute(const char *command
, boolread_only
, longcount
)
Описание
SPI_execute
выполняет заданную команду SQL для получения строк в количестве, ограниченном count
. С параметром read_only
, равным true
, команда должна только читать данные; это несколько сокращает издержки на её выполнение.
Эту функцию можно вызывать только из подключённой функции на C.
Если count
равен 0, команда выполняется для всех строк, к которым она применима. Если count
больше нуля, будет получено не более чем count
строк; выполнение команды остановится при достижении этого предела, практически так же, как и с предложением LIMIT
в запросе. Например, команда:
SPI_execute("SELECT * FROM foo", true, 5);
получит из таблицы не более 5 строк. Заметьте, что это ограничение действует, только когда команда действительно возвращает строки. Например, эта команда:
SPI_execute("INSERT INTO foo SELECT * FROM bar", false, 5);
вставляет все строки из bar
, игнорируя параметр count
. Однако команда
SPI_execute("INSERT INTO foo SELECT * FROM bar RETURNING *", false, 5);
вставит не более 5 строк, так как её выполнение будет остановлено после получения пятой строки, выданной предложением RETURNING
.
В одной строке можно передать несколько команд; SPI_execute
возвращает результат команды, выполненной последней. Параметр count
при этом будет применяться к каждой команде по отдельности (несмотря даже на то, что возвращён будет только последний результат). Это ограничение не будет распространяться на скрытые команды, генерируемые правилами.
Когда параметр read_only
равен false
, SPI_execute
увеличивает счётчик команд и получает новый снимок перед выполнением каждой очередной команды в строке. Этот снимок фактически не меняется при текущем уровне изоляции транзакций SERIALIZABLE
или REPEATABLE READ
, но в режиме READ COMMITTED
после обновления снимка очередная команда может видеть результаты только что зафиксированных транзакций из других сеансов. Это важно для согласованного поведения, когда команды модифицируют базу данных.
Когда параметр read_only
равен true
, SPI_execute
не обновляет снимок и не увеличивает счётчик команд, и допускает в строке команд только SELECT
. Заданные команды выполняются со снимком, ранее полученным для окружающего запроса. Этот режим выполнения несколько быстрее режима чтения/записи вследствие исключения издержек, связанных с отдельными командами. Он также позволяет создавать подлинно стабильные функции: так как последующие вызовы в транзакции будут использовать один снимок, результаты команд не изменятся.
Смешивать команды, только читающие, с командами, читающими и пишущими, в одной процедуре, использующей SPI, обычно неразумно; запросы только на чтение не увидят результатов изменений в базе данных, произведённых пишущими запросами.
Число строк, которые были фактически обработаны командой (последней), возвращается в глобальной переменной SPI_processed
. Если эта функция возвращает значение SPI_OK_SELECT
, SPI_OK_INSERT_RETURNING
, SPI_OK_DELETE_RETURNING
или SPI_OK_UPDATE_RETURNING
, вы можете обратиться по глобальному указателю SPITupleTable *SPI_tuptable
и прочитать строки результата. Некоторые служебные команды (например, EXPLAIN
) также возвращают наборы строк, и SPI_tuptable
будет содержать их результаты и в этих случаях. Другие вспомогательные команды (COPY
, CREATE TABLE AS
) не возвращают набор строк, так что указатель SPI_tuptable
равен NULL, но они так же возвращают число обработанных строк в SPI_processed
.
Структура SPITupleTable
определена так:
typedef struct SPITupleTable { /* Открытые члены */ TupleDesc tupdesc; /* дескриптор кортежа */ HeapTuple *vals; /* массив кортежей */ uint64 numvals; /* число фактически представленных кортежей */ /* Закрытые члены, не предназначенные для внешнего использования */ uint64 alloced; /* зарезервированное в памяти число элементов vals */ MemoryContext tuptabcxt; /* контекст таблицы результатов в памяти */ slist_node next; /* ссылка для внутреннего обслуживания */ SubTransactionId subid; /* подтранзакция, создавшая структуру tuptable */ } SPITupleTable;
Поля tupdesc
, vals
и numvals
могут использоваться кодом, вызывающим SPI, остальные поля являются внутренними. vals
представляет собой массив указателей на кортежи. Число записей в нём указывается в numvals
(по некоторым историческим причинам это число также возвращается в SPI_processed
). Поле tupdesc
содержит дескриптор кортежа, который вы сможете передать функциям SPI, работающими с кортежами.
SPI_finish
освобождает все структуры SPITupleTable
, размещённые в памяти для текущей функции на C. Вы можете освободить структуру конкретной результирующей таблицы, если она вам не нужна, вызвав SPI_freetuptable
.
Аргументы
const char *
command
строка с командой, которая должна быть выполнена
bool
read_only
true
для режима выполнения «только чтение»long
count
максимальное число строк, которое должно быть возвращено; с
0
ограничения нет
Возвращаемое значение
Если команда была выполнена успешно, возвращается одно из следующих (неотрицательных) значений:
SPI_OK_SELECT
если выполнялась команда
SELECT
(но неSELECT INTO
)SPI_OK_SELINTO
если выполнялась команда
SELECT INTO
SPI_OK_INSERT
если выполнялась команда
INSERT
SPI_OK_DELETE
если выполнялась команда
DELETE
SPI_OK_UPDATE
если выполнялась команда
UPDATE
SPI_OK_INSERT_RETURNING
если выполнялась команда
INSERT RETURNING
SPI_OK_DELETE_RETURNING
если выполнялась команда
DELETE RETURNING
SPI_OK_UPDATE_RETURNING
если выполнялась команда
UPDATE RETURNING
SPI_OK_UTILITY
если выполнялась служебная команда (например,
CREATE TABLE
)SPI_OK_REWRITTEN
если команда была преобразована правилом в команду другого вида (например,
UPDATE
стал командойINSERT
).
В случае ошибки возвращается одно из следующих отрицательных значений:
SPI_ERROR_ARGUMENT
если в качестве
command
переданNULL
илиcount
меньше 0SPI_ERROR_COPY
при попытке выполнить
COPY TO stdout
илиCOPY FROM stdin
SPI_ERROR_TRANSACTION
при попытке выполнить команду управления транзакциями (
BEGIN
,COMMIT
,ROLLBACK
,SAVEPOINT
,PREPARE TRANSACTION
,COMMIT PREPARED
,ROLLBACK PREPARED
или любую их вариацию)SPI_ERROR_OPUNKNOWN
если тип команды неизвестен (такого быть не должно)
SPI_ERROR_UNCONNECTED
если вызывается из неподключённой функции на C
Примечания
Все функции SPI, выполняющие запросы, заполняют и SPI_processed
, и SPI_tuptable
(только указатель, но не содержимое структуры). Сохраните эти две глобальные переменные в локальных переменных функции на C, если хотите обращаться к таблице результата SPI_execute
или другой функции, выполняющей запрос, в нескольких вызовах процедуры.