9.17. Funções de manejo de sequência

9.17. Funções de manejo de sequência
Anterior	Acima	Capítulo 9. Funções e operadores	Principal	Próxima

9.17. Funções de manejo de sequência #

Esta seção descreve as funções que operam em objetos de sequência, também chamados de geradores de sequência, ou apenas sequências. Os objetos de sequência são tabelas especiais de uma única linha criadas por CREATE SEQUENCE. Os objetos de sequência são comumente usados para gerar identificadores únicos para as linhas de uma tabela. As funções de sequência, listadas na Tabela 9.55, fornecem métodos multiusuários simples e seguros para obter valores de sequência sucessivos de objetos de sequência.

Tabela 9.55. Funções de sequência

Função Descrição
`nextval` ( `regclass` ) → `bigint` Avança o objeto de sequência para seu próximo valor e retorna esse valor. Isto é feito atomicamente: mesmo que várias sessões executem `nextval` simultaneamente, cada uma receberá com segurança um valor de sequência distinto. Se o objeto de sequência foi criado com os parâmetros padrão, as chamadas sucessivas à função `nextval` retornarão valores sucessivos começando com 1. Podem ser obtidos outros comportamentos usando os parâmetros apropriados no comando CREATE SEQUENCE. Esta função requer o privilégio `USAGE` ou `UPDATE` na sequência.
`setval` ( `regclass`, `bigint` [, `boolean` ] ) → `bigint` Define o valor corrente do objeto de sequência e, opcionalmente, seu sinalizador `is_called`. A forma com dois parâmetros define o campo `last_value` da sequência com o valor especificado, e define seu campo `is_called` como `true`, significando que o próximo `nextval` avançará a sequência antes de retornar o valor. O valor a ser informado pela função `currval` também é definido como o valor especificado. Na forma com três parâmetros, `is_called` pode ser definido tanto como `true` quanto como `false`. Como `true` tem o mesmo efeito que a forma com dois parâmetros. Se for definido como `false`, o próximo `nextval` retornará o valor especificado, e o avanço da sequência começará com o `nextval` seguinte. Além disso, o valor informado por `currval` não é alterado neste caso. Por exemplo, SELECT setval('myseq', 42); Retorna 42. O próximo `nextval` retornará 43 SELECT setval('myseq', 42, true); Idêntico ao acima SELECT setval('myseq', 42, false); Retorna 42. O próximo `nextval` retornará 42 também O resultado retornado por `setval` é apenas o valor de seu segundo argumento. Esta função requer o privilégio `UPDATE` na sequência.
`currval` ( `regclass` ) → `bigint` Retorna o valor obtido mais recentemente por `nextval` para esta sequência na sessão corrente. (É gerado um erro se `nextval` não foi chamado anteriormente para esta sequência nesta sessão.) Como retorna o valor da sessão local, esta função fornece uma resposta previsível mesmo se outras sessões executaram, ou não, `nextval` depois da sessão corrente. Esta função requer o privilégio `USAGE` ou `SELECT` na sequência.
`lastval` () → `bigint` Retorna o valor retornado mais recentemente por `nextval` na sessão corrente. Esta função é idêntica a `currval`, exceto que ao invés de aceitar o nome da sequência como argumento, se refere a qualquer sequência à qual `nextval` foi aplicada mais recentemente na sessão corrente. É um erro chamar `lastval` se `nextval` ainda não foi chamado na sessão corrente. Esta função requer o privilégio `USAGE` ou `SELECT` na última sequência usada.

Função

Descrição

nextval ( regclass ) → bigint

Avança o objeto de sequência para seu próximo valor e retorna esse valor. Isto é feito atomicamente: mesmo que várias sessões executem nextval simultaneamente, cada uma receberá com segurança um valor de sequência distinto. Se o objeto de sequência foi criado com os parâmetros padrão, as chamadas sucessivas à função nextval retornarão valores sucessivos começando com 1. Podem ser obtidos outros comportamentos usando os parâmetros apropriados no comando CREATE SEQUENCE.

Esta função requer o privilégio USAGE ou UPDATE na sequência.

setval ( regclass, bigint [, boolean ] ) → bigint

Define o valor corrente do objeto de sequência e, opcionalmente, seu sinalizador is_called. A forma com dois parâmetros define o campo last_value da sequência com o valor especificado, e define seu campo is_called como true, significando que o próximo nextval avançará a sequência antes de retornar o valor. O valor a ser informado pela função currval também é definido como o valor especificado. Na forma com três parâmetros, is_called pode ser definido tanto como true quanto como false. Como true tem o mesmo efeito que a forma com dois parâmetros. Se for definido como false, o próximo nextval retornará o valor especificado, e o avanço da sequência começará com o nextval seguinte. Além disso, o valor informado por currval não é alterado neste caso. Por exemplo,

SELECT setval('myseq', 42);         Retorna 42. O próximo nextval retornará 43
SELECT setval('myseq', 42, true);   Idêntico ao acima
SELECT setval('myseq', 42, false);  Retorna 42. O próximo nextval retornará 42 também

O resultado retornado por setval é apenas o valor de seu segundo argumento.

Esta função requer o privilégio UPDATE na sequência.

currval ( regclass ) → bigint

Retorna o valor obtido mais recentemente por nextval para esta sequência na sessão corrente. (É gerado um erro se nextval não foi chamado anteriormente para esta sequência nesta sessão.) Como retorna o valor da sessão local, esta função fornece uma resposta previsível mesmo se outras sessões executaram, ou não, nextval depois da sessão corrente.

Esta função requer o privilégio USAGE ou SELECT na sequência.

lastval () → bigint

Retorna o valor retornado mais recentemente por nextval na sessão corrente. Esta função é idêntica a currval, exceto que ao invés de aceitar o nome da sequência como argumento, se refere a qualquer sequência à qual nextval foi aplicada mais recentemente na sessão corrente. É um erro chamar lastval se nextval ainda não foi chamado na sessão corrente.

Esta função requer o privilégio USAGE ou SELECT na última sequência usada.

Cuidado

Para evitar o bloqueio de transações concorrentes, que obtêm números da mesma sequência, o valor obtido pela função nextval não é recuperado para ser usado novamente se a transação que chamou a função for desfeita posteriormente, significando que o término anormal de transações, ou falhas no banco de dados, podem resultar em descontinuidades na sequência dos valores atribuídos. Também pode ocorrer sem que aconteça o término anormal da transação. Por exemplo, um INSERT com a cláusula ON CONFLICT irá computar a tupla a ser inserida, incluindo fazer qualquer chamada a nextval necessária, antes de detectar qualquer conflito que faria com que seguisse a regra ON CONFLICT. Portanto, os objetos de sequência do PostgreSQL não podem ser usados para obter sequências “sem descontinuidades”.

Da mesma forma, as alterações no estado da sequência feitas por setval são imediatamente visíveis pelas outras transações, e não são desfeitas se a transação que chamou a função for desfeita (roll back).

Se o agrupamento (cluster) de bancos de dados tiver problemas antes de efetivar uma transação contendo uma chamada à função nextval ou setval, a alteração de estado da sequência pode não ter chegado ao armazenamento persistente, de modo que é incerto se a sequência terá seu estado original ou atualizado após a reinicialização do agrupamento. Isto é inócuo para o uso da sequência dentro do banco de dados, porque outros efeitos de transações não confirmadas também não serão visíveis. No entanto, se for desejado usar um valor de sequência para propósitos persistentes fora do banco de dados, certifique-se de que a chamada à função nextval tenha sido efetivada antes de fazer isto.

A sequência a ser operada por uma função de sequência é especificada por um argumento do tipo de dados regclass, que é apenas o OID da sequência no catálogo do sistema pg_class. No entanto, não é necessário procurar o OID manualmente, porque o conversor de entrada do tipo de dados regclass faz esse trabalho. Veja a Seção 8.19 para obter detalhes.