CREATE SEQUENCE

примечание

Эта страница переведена при помощи нейросети GigaChat.

CREATE SEQUENCE — создание нового генератора последовательностей.

Синтаксис

CREATE [ { TEMPORARY | TEMP } | UNLOGGED ] SEQUENCE [ IF NOT EXISTS ] name
    [ AS data_type ]
    [ INCREMENT [ BY ] increment ]
    [ MINVALUE minvalue | NO MINVALUE ] [ MAXVALUE maxvalue | NO MAXVALUE ]
    [ START [ WITH ] start ] [ CACHE cache ] [ [ NO ] CYCLE ]
    [ OWNED BY { table_name.column_name | NONE } ]

Описание

CREATE SEQUENCE создает новый генератор последовательных номеров. Это включает создание и инициализацию новой специальной таблицы name с одной строкой. Владельцем последовательности становится пользователь, выполняющий команду.

Если указано имя схемы, последовательность будет создана в ней. Если схема не указана — используется текущая. Временные последовательности создаются в специальной схеме, поэтому при их создании нельзя указывать имя схемы. Имя последовательности должно быть уникальным среди всех других объектов в схеме (таблиц, индексов, представлений и других).

После создания последовательности для работы с ней используются функции nextval, currval, setval.

Хотя напрямую изменить значение последовательности нельзя, ее состояние можно посмотреть с помощью запроса:

SELECT * FROM name;

Поле last_value покажет последнее выделенное значение (для любой сессии). Однако оно может быстро устареть, если другие сессии параллельно вызывают nextval.

Параметры

TEMPORARY | TEMP

Создает временную последовательность, доступную только в текущей сессии. Она будет автоматически удалена при завершении сессии. Постоянные последовательности с тем же именем будут недоступны в этой сессии (если не использовать полное имя со схемой).

UNLOGGED

Создает нежурналируемую последовательность. Ее изменения не записываются в журнал WAL, такие последовательности неустойчивы к сбоям: после сбоя или неправильного завершения работы они сбрасываются в начальное состояние. Также они не реплицируются на резервные серверы.

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

IF NOT EXISTS

Подавляет ошибку, если объект с указанным именем уже существует, вместо этого будет выдано уведомление. Однако наличие объекта с таким именем не означает, что он идентичен тому, которое попытались создать (или что это именно последовательность).

name

Задает имя последовательности, при необходимости дополненное схемой, которая должна быть создана.

AS data_type

Задает тип данных последовательности (опциональный параметр). Допустимыми типами являются smallint, integer и bigint. bigint является значением по умолчанию. Тип данных определяет значения по умолчанию для минимального и максимального значений последовательности.

INCREMENT BY increment

Указывает шаг последовательности (опциональный параметр). Положительное значение создаст возрастающую последовательность, отрицательное — убывающую. Значение по умолчанию равно 1.

MINVALUE minvalue
NO MINVALUE

Определяет минимальное значение, которое может сгенерировать последовательность (опциональный параметр). Если этот параметр не указан или указан NO MINVALUE, то будут использоваться значения по умолчанию. Значение по умолчанию для возрастающей последовательности равно 1. Значение по умолчанию для убывающей последовательности равно минимальному значению типа данных.

MAXVALUE maxvalue
NO MAXVALUE

Определяет максимальное значение для последовательности (опциональный параметр). Если этот параметр не указан или указан NO MAXVALUE, то будут использоваться значения по умолчанию. Значение по умолчанию для возрастающей последовательности равно максимальному значению типа данных. Значение по умолчанию для убывающей последовательности равно -1.

START WITH start

Начальное значение последовательности (опциональный параметр). По умолчанию — minvalue (для возрастающей) или maxvalue (для убывающей).

CACHE cache

Указывает сколько значений предварительно сохранять в памяти (кешировать). Минимальное значение — 1 (без кеша). Значение по умолчанию — 1.

CYCLE
NO CYCLE

Зацикливает последовательность при достижении maxvalue или minvalue соответственно для возрастающей или убывающей последовательности. Когда этот предел достигается, следующим числом этих последовательностей будет соответственно minvalue или maxvalue.

Если указано NO CYCLE, любые вызовы к nextval после достижения последовательностью предельного значения будут возвращать ошибку. Если ни CYCLE, ни NO CYCLE не указаны, по умолчанию предполагается NO CYCLE.

OWNED BY table_name.column_name
OWNED BY NONE

Привязывает последовательность к столбцу таблицы. Если этот столбец (или вся таблица) будет удален — последовательность тоже удаляется. Таблица и последовательность должны иметь одного владельца и находиться в одной схеме.

OWNED BY NONE — последовательность не привязана ни к какому объекту (по умолчанию).

Примечания

Удаление последовательности выполняется командой DROP SEQUENCE.

Последовательности используют 64-битные числа (bigint), допустимый диапазон: от -9223372036854775808 до 9223372036854775807.

Вызовы nextval и setval не откатываются транзакциями. Поэтому если требуется обеспечить непрерывное назначение номеров последовательностей. Возможно построить непрерывное назначение с использованием исключительной блокировки таблицы, содержащей счетчик, но это решение намного дороже, чем объекты последовательностей, особенно если многим транзакциям одновременно требуются номера последовательностей.

Нежелательные результаты могут возникнуть при использовании последовательности с параметром CACHE, установленным в значение больше единицы, если эта последовательность используется одновременно несколькими сессиями. В такой ситуации каждая сессия при первом обращении к объекту последовательности выделяет и кеширует последовательный набор значений — сразу несколько, в количестве, указанном в CACHE. При этом значение last_value последовательности увеличивается сразу на соответствующее количество.

После этого последующие вызовы nextval в пределах той же сессии (в количестве CACHE = 1) просто возвращают уже зарезервированные значения из кеша, не обращаясь повторно к самой последовательности. Таким образом, если какая-либо часть этих предварительно выделенных значений не будет использована до завершения сессии, то такие значения будут потеряны, и в последовательности появятся «пробелы» — номера, которые больше не выдадутся, хотя и были заранее выделены.

Дополнительно стоит учитывать: хотя гарантируется, что разные сессии получат уникальные значения, порядок генерации значений может быть несогласованным при параллельной работе нескольких сессий. Например, при значении CACHE = 10 сессия A может зарезервировать значения от 1 до 10 и сразу вернуть nextval = 1, а сессия B почти одновременно зарезервирует значения от 11 до 20 и вернет nextval = 11 — еще до того, как сессия A успеет получить nextval = 2.

Из этого следует, что если:

• CACHE = 1, то можно быть уверенным, что значения nextval выдаются строго последовательно;
• CACHE > 1, можно лишь полагаться на уникальность значений, но не на их строго возрастающий порядок по времени вызова.

Также стоит иметь в виду, что поле last_value в объекте последовательности будет отражать последнее зарезервированное значение — то есть то, которое может быть еще не выдано ни одной сессии, но уже находится в кеше и ждет выдачи. Поэтому оно необязательно соответствует значению, возвращенному последним вызовом nextval.

Вызов setval не влияет на другие сессии, пока они не израсходуют свой кеш.

Примеры

Создание возрастающей последовательности под названием serial с начальным значением 101:

CREATE SEQUENCE serial START 101;

Получение следующего номера этой последовательности:

SELECT nextval('serial');

 nextval
---------
     101

Получение следующего номера этой последовательности:

SELECT nextval('serial');

 nextval
---------
     102

Использование этой последовательности в команде INSERT:

INSERT INTO distributors VALUES (nextval('serial'), 'nothing');

Изменение значения последовательности после COPY FROM:

BEGIN;
COPY distributors FROM 'input_file';
SELECT setval('serial', max(id)) FROM distributors;
END;

Совместимость

CREATE SEQUENCE соответствует стандарту SQL, за следующими исключениями:

• Получение следующего значения выполняется с использованием функции nextval(), а не выражения стандарта NEXT VALUE FOR.
• Выражение OWNED BY является расширением PostgreSQL.

Смотрите также

ALTER SEQUENCE, DROP SEQUENCE