9.17. Функции для работы с последовательностями

9.17. Функции для работы с последовательностями
Пред.	Наверх	Глава 9. Функции и операторы	Начало	След.

В этом разделе описаны функции для работы с объектами, представляющими последовательности. Такие объекты (также называемыми генераторами последовательностей или просто последовательностями) являются специальными таблицами из одной строки и создаются командой CREATE SEQUENCE. Используются они обычно для получения уникальных идентификаторов строк таблицы. Функции, перечисленные в Таблице 9.50, предоставляют простые и безопасные для параллельного использования методы получения очередных значений таких последовательностей.

Таблица 9.50. Функции для работы с последовательностями

Функция Описание
`nextval` ( `regclass` ) → `bigint` Продвигает объект последовательности к следующему значению и возвращает это значение. Это действие атомарно: даже если вызвать `nextval` параллельно в нескольких сеансах, в каждом вызове будет гарантированно получено неповторяющееся значение последовательности. Если объект последовательности создаётся с параметрами по умолчанию, при каждом очередном вызове `nextval` будет выдаваться следующее по порядку значение, начиная с 1. Изменить это поведение можно, установив соответствующие параметры команды CREATE SEQUENCE. Этой функции требуется право `USAGE` или `UPDATE` для последовательности.
`setval` ( `regclass`, `bigint` [, `boolean`] ) → `bigint` Устанавливает для объекта последовательности текущее значение и может также установить флаг `is_called`. В форме с двумя параметрами устанавливает для последовательности заданное значение поля `last_value` и значение `true` для флага `is_called`, показывающего, что при следующем вызове `nextval` последовательность должна сначала продвинуться к очередному значению, которое будет возвращено. При этом `currval` также возвратит заданное значение. В форме с тремя параметрами флагу `is_called` тоже можно присвоить `true` или `false`. Со значением `true` она действует так же, как и форма с двумя параметрами. Если же присвоить этому флагу значение `false`, первый вызов `nextval` после этого вернёт именно заданное значение, а продвижение последовательности произойдёт при последующем вызове `nextval`. Кроме того, значение, возвращаемое `currval` в этом случае, не меняется. Например: SELECT setval('myseq', 42); При следующем вызове `nextval` выдаст 43 SELECT setval('myseq', 42, true); То же самое SELECT setval('myseq', 42, false); При следующем вызове `nextval` выдаст 42 Результатом `setval` будет просто значение её второго аргумента. Этой функции требуется право `UPDATE` для последовательности.
`currval` ( `regclass` ) → `bigint` Возвращает значение, выданное при последнем вызове `nextval` для этой последовательности в текущем сеансе. (Если в данном сеансе `nextval` ни разу не вызывалась для данной последовательности, возвращается ошибка.) Так как это значение ограничено рамками сеанса, эта функция выдаёт предсказуемый результат вне зависимости от того, вызвалась ли впоследствии `nextval` в других сеансах или нет. Этой функции требуется право `USAGE` или `SELECT` для последовательности.
`lastval` () → `bigint` Возвращает значение, выданное при последнем вызове `nextval` в текущем сеансе. Эта функция подобна `currval`, но она не принимает в параметрах имя последовательности, а обращается к той последовательности, для которой вызывалась `nextval` в последний раз в текущем сеансе. Если в текущем сеансе функция `nextval` ещё не вызывалась, при вызове `lastval` произойдёт ошибка. Этой функции требуется право `USAGE` или `SELECT` для последней использованной последовательности.

Функция

Описание

nextval ( regclass ) → bigint

Продвигает объект последовательности к следующему значению и возвращает это значение. Это действие атомарно: даже если вызвать nextval параллельно в нескольких сеансах, в каждом вызове будет гарантированно получено неповторяющееся значение последовательности. Если объект последовательности создаётся с параметрами по умолчанию, при каждом очередном вызове nextval будет выдаваться следующее по порядку значение, начиная с 1. Изменить это поведение можно, установив соответствующие параметры команды CREATE SEQUENCE.

Этой функции требуется право USAGE или UPDATE для последовательности.

setval ( regclass, bigint [, boolean] ) → bigint

Устанавливает для объекта последовательности текущее значение и может также установить флаг is_called. В форме с двумя параметрами устанавливает для последовательности заданное значение поля last_value и значение true для флага is_called, показывающего, что при следующем вызове nextval последовательность должна сначала продвинуться к очередному значению, которое будет возвращено. При этом currval также возвратит заданное значение. В форме с тремя параметрами флагу is_called тоже можно присвоить true или false. Со значением true она действует так же, как и форма с двумя параметрами. Если же присвоить этому флагу значение false, первый вызов nextval после этого вернёт именно заданное значение, а продвижение последовательности произойдёт при последующем вызове nextval. Кроме того, значение, возвращаемое currval в этом случае, не меняется. Например:

SELECT setval('myseq', 42);           При следующем вызове nextval выдаст 43
SELECT setval('myseq', 42, true);     То же самое
SELECT setval('myseq', 42, false);    При следующем вызове nextval выдаст 42

Результатом setval будет просто значение её второго аргумента.

Этой функции требуется право UPDATE для последовательности.

currval ( regclass ) → bigint

Возвращает значение, выданное при последнем вызове nextval для этой последовательности в текущем сеансе. (Если в данном сеансе nextval ни разу не вызывалась для данной последовательности, возвращается ошибка.) Так как это значение ограничено рамками сеанса, эта функция выдаёт предсказуемый результат вне зависимости от того, вызвалась ли впоследствии nextval в других сеансах или нет.

Этой функции требуется право USAGE или SELECT для последовательности.

lastval () → bigint

Возвращает значение, выданное при последнем вызове nextval в текущем сеансе. Эта функция подобна currval, но она не принимает в параметрах имя последовательности, а обращается к той последовательности, для которой вызывалась nextval в последний раз в текущем сеансе. Если в текущем сеансе функция nextval ещё не вызывалась, при вызове lastval произойдёт ошибка.

Этой функции требуется право USAGE или SELECT для последней использованной последовательности.

Внимание

Во избежание блокирования параллельных транзакций, пытающихся получить значения одной последовательности, операция nextval никогда не откатывается; то есть, как только значение было выбрано, оно считается использованным и не будет возвращено снова. Это утверждение верно, даже когда окружающая транзакция впоследствии прерывается или вызывающий запрос никак не использует это значение. Например, команда INSERT с предложением ON CONFLICT вычислит кортеж, претендующий на добавление, произведя все требуемые вызовы nextval, прежде чем выявит конфликты, которые могут привести к отработке правил ON CONFLICT вместо добавления. В таких ситуациях в последовательности задействованных значений могут образовываться «дыры». Таким образом, объекты последовательностей PostgreSQL не годятся для получения непрерывных последовательностей.

В том же ключе любые изменения состояния последовательности, произведённые функцией setval, не отменяются при откате транзакции.

Вышеописанные функции, работающие с таблицами или индексами, принимают аргумент типа regclass, который представляет собой просто OID таблицы или индекса в системном каталоге pg_class. Однако вам не нужно вручную вычислять OID, так как процедура ввода значения regclass может сделать это за вас. За подробностями обратитесь к Разделу 8.19.