9.17. Fonctions de manipulation de séquence

» » »

Précédent	Niveau supérieur	Suivant
9.16. Fonctions et opérateurs JSON	Sommaire	9.18. Expressions conditionnelles

9.17. Fonctions de manipulation de séquence

Cette section décrit les fonctions pour opérer sur des objets séquence, aussi appelés des générateurs de séquence ou plus simplement séquences. Les objets séquence sont des tables spéciales à une ligne créées avec l'ordre CREATE SEQUENCE. Les objets séquence sont habituellement utilisés pour générer des identifiants uniques pour les lignes d'une table. Les fonctions pour séquence, listées dans Tableau 9.50, fournissent des méthodes simples, sûres pour la concurrence d'utilisateur, permettent d'obtenir des valeurs successives de séquence à partir d'objets séquence.

Tableau 9.50. Fonctions pour séquence

Fonction Description
`nextval` ( `regclass` ) → `bigint` Avance l'objet séquence à sa prochaine valeur et renvoie cette valeur. Ceci est fait de façon atomique : même si plusieurs sessions exécutent `nextval` en même temps, chacune recevra une valeur distincte de séquence. Si l'objet séquence a été créé avec les paramètres par défaut, les appels successifs à `nextval` renverront les valeurs successives en partant de 1. D'autres comportements peuvent être obtenus en utilisant les paramètres appropriés dans la commande CREATE SEQUENCE. Cette fonction nécessite le droit `USAGE` ou `UPDATE` sur la séquence.
`setval` ( `regclass`, `bigint` [, `boolean` ] ) → `bigint` Configure la valeur actuelle de l'objet séquence, et en option son drapeau `is_called`. La syntaxe à deux paramètres configure le champ `last_value` à la valeur indiquée et configure le champ `is_called` à la valeur `true`, signifiant que le prochain appel à `nextval` avancera la séquence avant de renvoyer la valeur. La valeur qui sera alors rapportée par `currval` est aussi configurée à la valeur indiquée. Dans la syntaxe à trois paramètres, `is_called` peut être configuré à `true` ou à `false`. `true` a le même effet que dans la syntaxe à deux paramètres. S'il est configuré à `false`, le prochain appel à `nextval` renverra exactement la valeur indiqué, et l'avancement de la séquence commence avec le `nextval` suivant. De plus, la valeur renvoyée par `currval` n'est pas modifiée dans ce cas. Par exemple, SELECT setval('myseq', 42); Le prochain `nextval` renverra 43 SELECT setval('myseq', 42, true); Identique SELECT setval('myseq', 42, false); Le prochain `nextval` renverra 42 Le résultat renvoyé par `setval` est simplement la valeur de son deuxième argument. Cette fonction nécessite le droit `UPDATE` sur la séquence.
`currval` ( `regclass` ) → `bigint` Renvoie la valeur la plus récemment obtenue par `nextval` pour cette séquence dans le session courante. (Une erreur est renvoyée si `nextval` n'a jamais été appelé par cette séquence dans cette session.) Comme cela renvoie une valeur locale à la session, la réponse est prévisible que d'autres sessions aient `nextval` ou pas depuis que la session courant l'a fait. Cette fonction nécessite le droit `USAGE` ou le droit `SELECT` sur la séquence.
`lastval` () → `bigint` Renvoie la valeur la plus récemment renvoyée par la fonction `nextval` dans la session courante. Cette fonction est identique à `currval`, sauf qu'au lieu de prendre le nom de la séquence en argument, elle se réfère à la dernière séquence utilisée avec `nextval` dans la session courante. Une erreur est renvoyé si `lastval` a été appelée alors que `nextval` ne l'a pas été dans la session courante. Cette fonction nécessite le droit `USAGE` ou le droit `SELECT` sur la dernière séquence utilisée.

Fonction

Description

nextval ( regclass ) → bigint

Avance l'objet séquence à sa prochaine valeur et renvoie cette valeur. Ceci est fait de façon atomique : même si plusieurs sessions exécutent nextval en même temps, chacune recevra une valeur distincte de séquence. Si l'objet séquence a été créé avec les paramètres par défaut, les appels successifs à nextval renverront les valeurs successives en partant de 1. D'autres comportements peuvent être obtenus en utilisant les paramètres appropriés dans la commande CREATE SEQUENCE.

Cette fonction nécessite le droit USAGE ou UPDATE sur la séquence.

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

Configure la valeur actuelle de l'objet séquence, et en option son drapeau is_called. La syntaxe à deux paramètres configure le champ last_value à la valeur indiquée et configure le champ is_called à la valeur true, signifiant que le prochain appel à nextval avancera la séquence avant de renvoyer la valeur. La valeur qui sera alors rapportée par currval est aussi configurée à la valeur indiquée. Dans la syntaxe à trois paramètres, is_called peut être configuré à true ou à false. true a le même effet que dans la syntaxe à deux paramètres. S'il est configuré à false, le prochain appel à nextval renverra exactement la valeur indiqué, et l'avancement de la séquence commence avec le nextval suivant. De plus, la valeur renvoyée par currval n'est pas modifiée dans ce cas. Par exemple,

SELECT setval('myseq', 42);           Le prochain nextval renverra 43
SELECT setval('myseq', 42, true);     Identique
SELECT setval('myseq', 42, false);    Le prochain nextval renverra 42

Le résultat renvoyé par setval est simplement la valeur de son deuxième argument.

Cette fonction nécessite le droit UPDATE sur la séquence.

currval ( regclass ) → bigint

Renvoie la valeur la plus récemment obtenue par nextval pour cette séquence dans le session courante. (Une erreur est renvoyée si nextval n'a jamais été appelé par cette séquence dans cette session.) Comme cela renvoie une valeur locale à la session, la réponse est prévisible que d'autres sessions aient nextval ou pas depuis que la session courant l'a fait.

Cette fonction nécessite le droit USAGE ou le droit SELECT sur la séquence.

lastval () → bigint

Renvoie la valeur la plus récemment renvoyée par la fonction nextval dans la session courante. Cette fonction est identique à currval, sauf qu'au lieu de prendre le nom de la séquence en argument, elle se réfère à la dernière séquence utilisée avec nextval dans la session courante. Une erreur est renvoyé si lastval a été appelée alors que nextval ne l'a pas été dans la session courante.

Cette fonction nécessite le droit USAGE ou le droit SELECT sur la dernière séquence utilisée.

Attention

Pour éviter le blocage de transactions concurrentes pour l'obtention de nombres provenant de la même séquence, la valeur obtenue par nextval n'est pas réclamée pour une ré-utilisation si la transaction appelante s'annule après coup. Ceci signifie que des annulations de transaction ou des crashs de bases de données peuvent avoir pour conséquence des trous dans la séquence des valeurs affectées. Ceci peut aussi survenir sans annulation de transaction. Par exemple, un INSERT avec une clause ON CONFLICT calculera la ligne à insérer, incluant tout appel nécessaire à nextval, avant de détecter un conflit qui causera la poursuite sur la règle ON CONFLICT. De ce fait, les objets séquences de PostgreSQL ne peuvent pas être utilisées pour obtenir des séquences « sans trou » .

De la même façon, les changements d'état de séquence réalisées par setval sont immédiatement visibles aux autres transactions, et ne sont pas annulées si la transaction appelante annule ses modifications.

Si l'instance s'arrête brutalement avant de valider une transaction ayant exécuté un appel à nextval ou setval, le changement d'état de la séquence pourrait ne pas arriver jusqu'au stockage permanent, donc l'état de la séquence n'est pas certain, uqil soit à sa valeur d'originie ou à sa nouvelle valeur après le redémarrage de l'instance. Ceci n'est pas grave pour l'utilisation de la séquence dans la base car les autres effets des transactions non valides ne seront pas visibles. Néanmoins, si vous souhaitez utiliser une valeur de séquence pour un stockage persistant hors de la base, assurez-vous que l'appel à nextval soit validé avant de l'utiliser hors base.

La séquence à traiter par une fonction de séquence est indiquée par un argument regclass, qui est simplement l'OID de la séquence dans le catalogue système pg_class. Vous n'avez pas besoin de rechercher l'OID manuellement car le convertisseur en entrée du type de donnée regclass fera ce travail pour vous? Écrivez simplement le nom de la séquence entre guillemets simples pour qu'il ressemble à une constante littérale. POur des raisons de compatibilité avec la gestion des noms SQL habituels, la chaîne sera convertie en minuscule, sauf si elle contient des guillemets doubles autour du nom de la séquence. De ce fait :

nextval('foo')      opère sur la séquence foo
nextval('FOO')      opère sur la séquence foo
nextval('"Foo"')    opère sur la séquence Foo

Le nom de la séquence peut être qualifié du nom du schéma si nécessaire :

nextval('myschema.foo')     opère sur myschema.foo
nextval('"myschema".foo')   identique à ci-dessus
nextval('foo')              recherche foo dans le chemin de recherche

Voir Section 8.19 pour plus d'informations sur regclass.

Note

Avant PostgreSQL 8.1, les arguments des fonctions séquence étaient de type text, et non pas regclass, et la conversion décrite ci-dessus partant d'une chaîne de texte pour aboutir à une valeur OID ne surviendrait qu'au moment de l'exécution pour chaque appel. Pour des raisons de compatibilité, ce fonctionnement existe toujours, mais en interne, il est maintenant géré comme une conversion implicite de text vers regclass avant que la fonction ne soit exécutée.

Quand vous écrivez l'argument d'une fonction séquence comme une chaîne de caractères sans fioritures, il devient une constante de type regclass. Comme il s'agit juste d'un OID, il tracer la séquence identifiée à l'origine malgré un renommage ultérieur, une réaffectation de schéma, etc. Le comportement de « référence en avance » est généralement désirable pour les références de séquence dans les valeurs par défaut des colonnes ou dans les vues. Cependant, quelques fois, vous pourriez vouloir du « référence tardive » où la référence de la séquence est résolue à l'exécution. Pour obtenir ce comportement de référence tardive, forcez la constante à être stockée sous le type text au lieu de regclass :

nextval('foo'::text)      foo is looked up at runtime

Notez que la référence tardive était le seul comportement supporté pour les versions de PostgreSQL antérieures à la 8.1, donc vous pourriez avoir besoin de préserver cette sémantique dans les anciennes applications.

Bien sûr, l'argument d'une fonction séquence peut être une expression ainsi qu'une constante. S'il s'agit une expression de type texte, alors la conversion implicite résultera en une recherche lors de l'exécution.