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:
Avança o objeto de seqüência para seu próximo valor e retorna este valor. Isto é feito atomicamente: mesmo que várias sessões executem nextval ao mesmo tempo, cada uma delas receberá um valor distinto da seqüência com segurança.
Retorna o valor retornado mais recentemente por nextval 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.
Redefine o valor do contador do objeto de seqüência. A forma com dois parâmetros define o campo last_value (último valor) da seqüência com o valor especificado, e define o campo is_called como true, indicando que o próximo nextval 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() retornará 43
SELECT setval('foo', 42, true); o mesmo acima
SELECT setval('foo', 42, false); o próximo nextval() retornará 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 nextval nunca é desfeita (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 o nextval seja 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ções setval nunca são desfeitas, 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; consulte a página de referência deste comando para obter informações adicionais.
