SPI_execute

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

Синтаксис

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

Описание

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 или SPI_OK_MERGE_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_MERGE

если выполнялась команда MERGE

SPI_OK_INSERT_RETURNING

если выполнялась команда INSERT RETURNING

SPI_OK_DELETE_RETURNING

если выполнялась команда DELETE RETURNING

SPI_OK_UPDATE_RETURNING

если выполнялась команда UPDATE RETURNING

SPI_OK_MERGE_RETURNING

если выполнялась команда MERGE 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

если вызывается из неподключённой функции на C

Примечания

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