Esta seção descreve as funções do PostgreSQL que operam com objetos de seqüência. Os objetos de seqüência (também chamados de geradores de seqüência, ou simplesmente de seqüências), são tabelas especiais de um única linha criadas pelo comando CREATE SEQUENCE. O objeto de seqüência é usado normalmente para gerar identificadores únicos para linhas de tabelas. As funções de seqüência, listadas na Tabela 9-36 , fornecem métodos simples, seguros para multiusuários, para obter valores sucessivos da seqüência a partir dos objetos de seqüência.
Tabela 9-36. Funções de seqüência
| Função | Tipo retornado | Descrição |
|---|---|---|
nextval(text) |
bigint | Avança a seqüência e retorna o novo valor |
currval(text) |
bigint | Retorna o valor obtido mais recentemente por nextval |
setval(text, bigint) |
bigint | Define o valor corrente da seqüência |
setval(text, bigint, boolean) |
bigint | Define o valor corrente da seqüência e o sinalizador is_called |
Por motivos históricos, a seqüência a ser operada pela chamada da função de seqüência é especificada por um argumento que é um texto em uma cadeia de caracteres. Para obter alguma compatibilidade com o tratamento usual dos nomes SQL, a função de seqüência converte as letras do argumento em minúsculas, a não ser que a cadeia de caracteres esteja entre aspas. Portanto
nextval('foo') opera na seqüência foo
nextval('FOO') opera na seqüência foo
nextval('"Foo"') opera na seqüência Foo
Havendo necessidade, o nome da seqüência pode ser qualificado pelo esquema:
nextval('meu_esquema.foo') opera em meu_esquema.foo
nextval('"meu_esquema".foo') o mesmo acima
nextval('foo') procura por foo no caminho de procura
É claro que o texto do argumento pode ser o resultado de uma expressão, e não somente um literal simples, o que algumas vezes é útil.
As funções de seqüência disponíveis são:
nextvalnextval simultaneamente, cada uma recebe um valor distinto da seqüência com segurança.
currvalnextval para esta seqüência na sessão corrente (relata erro se nextval nunca tiver sido chamada para esta seqüência nesta sessão). Deve ser observado que como é retornado o valor da sessão local, uma resposta previsível é obtida mesmo que outras sessões tenham executado nextval após a sessão corrente tê-lo feito.
setvalnextval avançará a seqüência antes de retornar o valor. Na forma com três parâmetros, is_called pode ser definido tanto como true quanto como false. Se for definido como false, o próximo nextval retornará o próprio valor especificado, e o avanço da seqüência somente começará no nextval seguinte. Por exemplo,
SELECT setval('foo', 42); o próximo nextval() retorna 43
SELECT setval('foo', 42, true); o mesmo acima
SELECT setval('foo', 42, false); o próximo nextval() retorna 42
O resultado retornado por setval é simplesmente o valor de seu segundo argumento.
Importante: Para evitar o bloqueio de transações simultâneas que obtêm números de uma mesma seqüência, a operação
nextvalnunca é cancelada (rolled back); ou seja, após o valor ser obtido este passa a ser considerado como tendo sido usado, mesmo que a transação que executou onextvalseja interrompida posteriormente. Isto significa que as transações interrompidas podem deixar "buracos" não utilizados na seqüência de valores atribuídos. Além disso, as operaçõessetvalnunca são canceladas, também.
Se o objeto de seqüência tiver sido criado com os parâmetros padrão, as chamadas à nextval() retornam valores sucessivos começando por um. Outros comportamentos podem ser obtidos utilizando parâmetros especiais no comando
CREATE SEQUENCE
; veja a página de referência deste comando para obter mais informações.