Postgres Pro Enterprise : Документация: 9.6: SPI_execute : Компания Postgres Professional

SPI_execute
Пред.	Наверх	45.1. Интерфейсные функции	Начало	След.

SPI_execute

SPI_execute — выполнить команду

Синтаксис

int SPI_execute(const char * command, bool read_only, long count)

Описание

SPI_execute выполняет заданную команду SQL для получения строк в количестве, ограниченном count. С параметром read_only, равным true, команда должна только читать данные; это несколько сокращает издержки на её выполнение.

Эту функцию можно вызывать только из подключённой процедуры.

Если 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
{
    MemoryContext tuptabcxt;    /* контекст таблицы результатов в памяти */
    uint64      alloced;        /* число зарезервированных в памяти значений */
    uint64      free;           /* число свободных значений */
    TupleDesc   tupdesc;        /* дескриптор строки */
    HeapTuple  *vals;           /* данные строк */
} SPITupleTable;

vals представляет собой массив указателей на строки. (Число записей в нём указывается в SPI_processed.) Поле tupdesc содержит дескриптор строки, который вы сможете передать функциям SPI, работающими со строками. Поля tuptabcxt, alloced и free предназначены для внутреннего использования, а не для процедур, работающих с SPI.

SPI_finish освобождает все структуры SPITupleTable, размещённые в памяти для текущей процедуры. Вы можете освободить структуру конкретной результирующей таблицы, если она вам не нужна, вызвав 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 меньше 0
SPI_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: если вызывается из неподключённой процедуры

Замечания

Все функции SPI, выполняющие запросы, заполняют и SPI_processed, и SPI_tuptable (только указатель, но не содержимое структуры). Сохраните эти две глобальные переменные в локальных переменных процедуры, если хотите обращаться к таблице результата SPI_execute или другой функции, выполняющей запрос, в нескольких вызовах процедуры.

Пред.	Начало	След.
SPI_pop	Наверх	SPI_exec

SPI_execute
Prev	Up	45.1. Interface Functions	Home	Next

SPI_execute

SPI_execute — execute a command

Synopsis

int SPI_execute(const char * command, bool read_only, long count)

Description

SPI_execute executes the specified SQL command for count rows. If read_only is true, the command must be read-only, and execution overhead is somewhat reduced.

This function can only be called from a connected procedure.

If count is zero then the command is executed for all rows that it applies to. If count is greater than zero, then no more than count rows will be retrieved; execution stops when the count is reached, much like adding a LIMIT clause to the query. For example,

SPI_execute("SELECT * FROM foo", true, 5);

will retrieve at most 5 rows from the table. Note that such a limit is only effective when the command actually returns rows. For example,

SPI_execute("INSERT INTO foo SELECT * FROM bar", false, 5);

inserts all rows from bar, ignoring the count parameter. However, with

SPI_execute("INSERT INTO foo SELECT * FROM bar RETURNING *", false, 5);

at most 5 rows would be inserted, since execution would stop after the fifth RETURNING result row is retrieved.

You can pass multiple commands in one string; SPI_execute returns the result for the command executed last. The count limit applies to each command separately (even though only the last result will actually be returned). The limit is not applied to any hidden commands generated by rules.

When read_only is false, SPI_execute increments the command counter and computes a new snapshot before executing each command in the string. The snapshot does not actually change if the current transaction isolation level is SERIALIZABLE or REPEATABLE READ, but in READ COMMITTED mode the snapshot update allows each command to see the results of newly committed transactions from other sessions. This is essential for consistent behavior when the commands are modifying the database.

When read_only is true, SPI_execute does not update either the snapshot or the command counter, and it allows only plain SELECT commands to appear in the command string. The commands are executed using the snapshot previously established for the surrounding query. This execution mode is somewhat faster than the read/write mode due to eliminating per-command overhead. It also allows genuinely stable functions to be built: since successive executions will all use the same snapshot, there will be no change in the results.

It is generally unwise to mix read-only and read-write commands within a single function using SPI; that could result in very confusing behavior, since the read-only queries would not see the results of any database updates done by the read-write queries.

The actual number of rows for which the (last) command was executed is returned in the global variable SPI_processed. If the return value of the function is SPI_OK_SELECT, SPI_OK_INSERT_RETURNING, SPI_OK_DELETE_RETURNING, or SPI_OK_UPDATE_RETURNING, then you can use the global pointer SPITupleTable *SPI_tuptable to access the result rows. Some utility commands (such as EXPLAIN) also return row sets, and SPI_tuptable will contain the result in these cases too. Some utility commands (COPY, CREATE TABLE AS) don't return a row set, so SPI_tuptable is NULL, but they still return the number of rows processed in SPI_processed.

The structure SPITupleTable is defined thus:

typedef struct
{
    MemoryContext tuptabcxt;    /* memory context of result table */
    uint64      alloced;        /* number of alloced vals */
    uint64      free;           /* number of free vals */
    TupleDesc   tupdesc;        /* row descriptor */
    HeapTuple  *vals;           /* rows */
} SPITupleTable;

vals is an array of pointers to rows. (The number of valid entries is given by SPI_processed.) tupdesc is a row descriptor which you can pass to SPI functions dealing with rows. tuptabcxt, alloced, and free are internal fields not intended for use by SPI callers.

SPI_finish frees all SPITupleTables allocated during the current procedure. You can free a particular result table earlier, if you are done with it, by calling SPI_freetuptable.

Arguments

const char * command: string containing command to execute
bool read_only: true for read-only execution
long count: maximum number of rows to return, or 0 for no limit

Return Value

If the execution of the command was successful then one of the following (nonnegative) values will be returned:

SPI_OK_SELECT: if a SELECT (but not SELECT INTO) was executed
SPI_OK_SELINTO: if a SELECT INTO was executed
SPI_OK_INSERT: if an INSERT was executed
SPI_OK_DELETE: if a DELETE was executed
SPI_OK_UPDATE: if an UPDATE was executed
SPI_OK_INSERT_RETURNING: if an INSERT RETURNING was executed
SPI_OK_DELETE_RETURNING: if a DELETE RETURNING was executed
SPI_OK_UPDATE_RETURNING: if an UPDATE RETURNING was executed
SPI_OK_UTILITY: if a utility command (e.g., CREATE TABLE) was executed
SPI_OK_REWRITTEN: if the command was rewritten into another kind of command (e.g., UPDATE became an INSERT) by a rule.

On error, one of the following negative values is returned:

SPI_ERROR_ARGUMENT: if command is NULL or count is less than 0
SPI_ERROR_COPY: if COPY TO stdout or COPY FROM stdin was attempted
SPI_ERROR_TRANSACTION: if a transaction manipulation command was attempted (BEGIN, COMMIT, ROLLBACK, SAVEPOINT, PREPARE TRANSACTION, COMMIT PREPARED, ROLLBACK PREPARED, or any variant thereof)
SPI_ERROR_OPUNKNOWN: if the command type is unknown (shouldn't happen)
SPI_ERROR_UNCONNECTED: if called from an unconnected procedure

Notes

All SPI query-execution functions set both SPI_processed and SPI_tuptable (just the pointer, not the contents of the structure). Save these two global variables into local procedure variables if you need to access the result table of SPI_execute or another query-execution function across later calls.

Prev	Home	Next
SPI_pop	Up	SPI_exec