Descrição

O comando CREATE SEQUENCE define um novo gerador de sequência de números. Isto envolve criar e inicializar uma nova tabela especial de uma única linha com o nome nome_da_sequência. O usuário que executa o comando se torna o dono da sequência.

Se for fornecido o nome do esquema, a sequência será criada no esquema especificado. Caso contrário, será criada no esquema corrente. As sequências temporárias existem em um esquema especial, portanto, não pode ser fornecido o nome do esquema ao criar uma sequência temporária. O nome da sequência deve ser diferente do nome de qualquer outra relação (tabela, sequência, índice, visão, visão materializada ou tabela estrangeira) no mesmo esquema.

Após a sequência ser criada, podem ser usadas as funções nextval, currval, e setval para operar na sequência. Estas funções estão documentadas na Funções para manusear sequência.

Embora não se possa atualizar uma sequência diretamente, pode ser usada uma consulta como

SELECT * FROM nome_da_sequência;

para examinar os parâmetros e o estado corrente da sequência. Em particular, o campo last_value da sequência mostra o último valor alocado por qualquer sessão. (Obviamente, este valor pode estar obsoleto no momento em que for visto, caso outras sessões estejam fazendo chamadas à função nextval ativamente.)

Parâmetros

Notas

O comando DROP SEQUENCE remove a sequência.

As sequências são baseadas na aritmética do tipo de dados bigint, portanto, o intervalo não pode exceder o intervalo de um número inteiro de oito bytes (-9223372036854775808 a 9223372036854775807).

Como as chamadas às funções nextval e setval nunca são desfeitas, os objetos de sequência não podem ser usados se for necessária uma atribuição “sem buracos” de números sequenciais. É possível construir atribuições “sem buracos” usando bloqueio exclusivo de uma tabela contendo o contador; mas esta solução tem um custo maior do que os geradores de sequência, especialmente se muitas transações precisarem de números de sequência simultaneamente.

Podem acontecer resultados não esperados se for usada uma configuração de cache maior que um, para um gerador de sequência que será usado simultaneamente por várias sessões. Cada sessão irá alocar e armazenar em cache valores sucessivos de sequência durante o acesso ao gerador de sequência, e aumentar o último valor (campo last_value) do gerador de sequência de acordo. Então, os próximos cache-1 usos de nextval dentro dessa sessão simplesmente retornam os valores pré-alocados sem tocar no gerador de sequência. Portanto, quaisquer números alocados, mas não utilizados em uma sessão, serão perdidos quando esta sessão terminar, resultando em “buracos” na sequência.

Além disso, embora seja garantido que várias sessões obtenham valores de sequência distintos, os valores podem ser gerados fora de sequência quando todas as sessões são consideradas. Por exemplo, com uma configuração de cache igual a 10, a sessão A pode reservar valores de 1 a 10 e retornar nextval=1, então a sessão B pode reservar os valores de 11 a 20 e retornar nextval=11 antes que a sessão A tenha gerado nextval=2. Portanto, com uma configuração de cache igual a um, é seguro assumir que os valores de nextval sejam gerados sequencialmente; com uma configuração de cache maior que um, deve-se assumir apenas que os valores de nextval são todos distintos, e não que sejam gerados puramente sequencialmente. Além disso, o campo last_value irá refletir o valor mais recente reservado por qualquer sessão, tenha ou não sido retornado por nextval.

Outra consideração é que setval executado nesta sequência não será notado pelas outras sessões, até que tenham usado todos os valores pré-alocados armazenados em cache.

Exemplos

Criar uma sequência ascendente chamada serial, começando em 101:

CREATE SEQUENCE serial START 101;

Obter o próximo número dessa sequência:

SELECT nextval('serial');

 nextval
---------
     101

Obter novamente o próximo número dessa sequência:

SELECT nextval('serial');

 nextval
---------
     102

Usar esta sequência em um comando INSERT:

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

Atualizar o valor da sequência após o comando COPY FROM:

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

CREATE TEMPORARY SEQUENCE zero_um
    INCREMENT BY 1
    MINVALUE 0
    MAXVALUE 1
    START WITH 0
    CYCLE
    CACHE 1;
CREATE SEQUENCE
SELECT nextval('zero_um'), nextval('zero_um'), nextval('zero_um');

 nextval | nextval | nextval
---------+---------+---------
       0 |       1 |       0
(1 linha)

SELECT nextval('zero_um'), nextval('zero_um'), nextval('zero_um');

 nextval | nextval | nextval
---------+---------+---------
       1 |       0 |       1
(1 linha)

Conformidade

O comando CREATE SEQUENCE está em conformidade com o padrão SQL, com as seguintes exceções:

Consulta

As informações sobre cada sequência no banco de dados podem ser consultadas através da visão do sistema pg_sequences.

Veja também