CREATE [ TEMPORARY | TEMP ] SEQUENCE nome_seq [ INCREMENT incremento ] [ MINVALUE valor_min ] [ MAXVALUE valor_max ] [ START início ] [ CACHE cache ] [ CYCLE ]
Se for especificado, o objeto de seqüência é criado somente para esta sessão, e automaticamente eliminado ao término da sessão. Uma seqüência permanente com o mesmo nome, caso exista, não será visível nesta sessão enquanto a seqüência temporária existir.
O nome da seqüência a ser criada.
A cláusula INCREMENT incremento é opcional. Um valor positivo cria uma seqüência ascendente, enquanto um valor negativo cria uma seqüência descendente. O valor padrão é um (1).
A cláusula opcional MINVALUE valor_min determina o valor mínimo que a seqüência pode gerar. Por padrão 1 e -2^63-1 para seqüências ascendentes e descendentes, respectivamente.
A cláusula opcional MAXVALUE valor_max determina o valor máximo para a seqüência. Por padrão 2^63-1 e -1 para seqüências ascendentes e descendentes, respectivamente.
A cláusula opcional START início permite a seqüência iniciar com qualquer valor. Por padrão, o valor inicial é igual a valor_min para seqüências ascendentes, e igual a valor_max para seqüências descendentes.
A opção CACHE cache permite que os números da seqüência sejam préviamente alocados e armazenados em memória para acesso mais rápido. O valor mínimo é 1 (somente um valor pode ser gerado de cada vez, ou seja, sem armazenamento em memória) e este também é o valor padrão.
A palavra chave opcional CYCLE pode ser utilizada para permitir a seqüência reiniciar quando o valor_max ou o valor_min for atingido pela seqüência ascendente ou descendente, respectivamente. Se o limite for atingido, o próximo número gerado será valor_min ou valor_max, respectivamente. Sem a cláusula CYCLE, após o limite ser atingido as chamadas à função nextval retornam um erro.
Mensagem retornada se o comando for executado com sucesso.
A seqüência especificada já existe.
O valor especificado para o início da seqüência está fora do intervalo.
O valor especificado para o início da seqüência está fora do intervalo.
Os valores mínimo e máximo estão inconsistentes.
O comando CREATE SEQUENCE cria um novo gerador de números seqüenciais no banco de dados em uso. Este comando envolve a criação e a inicialização de uma tabela nova com uma única linha com o nome nome_seq. O usuário que executa o comando se torna o dono do gerador.
Após a seqüência ser criada, podem ser utilizadas as funções nextval, currval e setval para trabalhar com a seqüência. Estas funções estão documentadas no Guia do Usuário.
Embora não seja possível atualizar uma seqüência diretamente, é possível realizar uma consulta do tipo
SELECT * FROM nome_seq;
para conhecer os parâmetros e o estado atual da seqüência. Em particular, o campo last_value da seqüência mostra o último valor alocado por qualquer processo servidor (É claro que este valor pode estar obsoleto na hora em que for exibido, se outros processos estiverem chamando a função nextval).
Caution |
Podem ocorrer resultados não esperados ao se especificar um valor maior do que 1 para cache em um objeto de seqüência utilizado ao mesmo tempo por vários servidores (backends). Cada servidor aloca e armazena em memória valores sucessivos da seqüência ao fazer um único acesso ao objeto de seqüência e incrementa o último valor (last_value) na forma correspondente. Então, a próxima utilização de cache-1 da função nextval neste servidor, simplesmente retorna os valores pré-alocados, sem tocar no objeto compartilhado. Desta forma, todos os valores alocados nesta sessão, mas não utilizados, são perdidos ao final da sessão. Além disso, embora seja garantido que os diversos servidores alocam valores distintos da seqüência, os valores podem ser gerados fora de seqüência quando são levados em conta todos os servidores. (Por exemplo, com um cache de 10, o servidor A pode reservar os valores de 1 a 10 e usar o próximo valor igual a 1, então o servidor B pode reservar os valores de 11 a 20 e usar o próximo valor igual a 11 antes do servidor A ter usado o próximo valor igual a 2). Assim, com um valor para cache igual a 1 é seguro assumir que os valores da função nextval são gerados seqüencialmente; com um valor para cache maior do que 1 pode-se assumir que os valores da função nextval são todos distintos, mas não que sejam gerados de forma puramente seqüencial. Além disso, o valor do campo last_value reflete o último valor reservado por qualquer servidor, independentemente de ter sido ou não retornado por uma chamada à função nextval. Outra consideração a ser feita, é que a função setval executada neste tipo de seqüência não vai fazer efeito em outro servidor até que este tenha utilizado todos os valores pré-alocados em memória. |
Use o comando DROP SEQUENCE para excluir uma seqüência.
As seqüências são baseadas em aritmética de tipo bigint, por isso a faixa de valores não pode ultrapassar a faixa permitida para números inteiros de 8 bytes (-9223372036854775808 a 9223372036854775807). Em algumas plataformas mais antigas pode não haver suporte do compilador para números inteiros de 8 bytes e, neste caso, as seqüências utilizam aritmética para o tipo regular integer (faixa de valores de -2147483648 a +2147483647).
Quando o valor para cache é maior do que 1, cada servidor utiliza sua própria memória para armazenar os números préviamente alocados. Os números armazenados em memória, mas não utilizados pela sessão atual, são perdidos, ocasionando uma seqüência cheia de "buracos".
Criar uma seqüência ascendente chamada serial, começando por 101:
CREATE SEQUENCE serial START 101;
Selecionar o próximo valor desta seqüência:
SELECT nextval('serial'); nextval ------- 114
Utilizar esta seqüência em um comando INSERT:
INSERT INTO distribuidores VALUES (nextval('serial'), 'nada');
Atualizar o valor da seqüência após executar o comando COPY FROM:
BEGIN; COPY distribuidores FROM 'arquivo_entrada'; SELECT setval('serial', max(id)) FROM distribuidores; END;