PostgreSQLLa base de données la plus sophistiquée au monde.

Version anglaise

9.16. Fonctions de manipulation de séquences

Cette section décrit les fonctions opérant sur les objets de type séquence, aussi appelés générateurs de séquence ou tout simplement séquences). Les séquences sont des tables spéciales, mono-lignes, créées avec la commande CREATE SEQUENCE(7). Les séquences sont habituellement utilisées pour générer des identifiants uniques de lignes d'une table. Les fonctions de séquence, listées dans le Tableau 9.46, « Fonctions séquence », fournissent des méthodes simples, et sûres en environnement multi-utilisateurs, d'obtention de valeurs successives à partir d'objets séquence.

Tableau 9.46. Fonctions séquence

Fonction Type de retour Description
currval(regclass) bigint Renvoie la valeur la plus récemment obtenue avec nextval pour la séquence indiquée
lastval() bigint Renvoie la valeur la plus récemment obtenue avec nextval pour toute séquence
nextval(regclass) bigint Incrémente la séquence et renvoie la nouvelle valeur
setval(regclass, bigint) bigint Positionne la valeur courante de la séquence
setval(regclass, bigint, boolean) bigint Positionne la valeur courante de la séquence et le drapeau is_called

La séquence à traiter par l'appel d'une fonction de traitement de séquences est identifiée par un argument regclass, qui n'est autre que l'OID de la séquence dans le catalogue système pg_class. Il n'est toutefois pas nécessaire de se préoccuper de la recherche de cet OID car le convertisseur de saisie du type de données regclass s'en charge. Il suffit d'écrire le nom de la séquence entre guillemets simples, de façon à le faire ressembler à un libellé. Pour obtenir une compatibilité avec la gestion des noms SQL ordinaires, la chaîne est convertie en minuscules, sauf si le nom de la séquence est entouré de guillemets doubles. Du coup :

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, au besoin, être qualifié du nom du schéma :

            nextval('mon_schema.foo')     opère sur mon_schema.foo
nextval('"mon_schema".foo')   identique à ci-dessus
nextval('foo')                parcourt le chemin de recherche
pour trouver foo

Voir la Section 8.18, « Types identifiant d'objet » pour plus d'informations sur regclass.

[Note]

Note

Avant la version 8.1 de PostgreSQL™, les arguments des fonctions de traitement de séquences étaient du type text, et non regclass. De ce fait, les conversions précédemment décrites d'une chaîne de caractères en valeur OID se produisaient à chaque appel. Pour des raisons de compatibilité, cette fonctionnalité existe toujours. Mais, en interne, un transtypage implicite est effectué entre text et regclass avant l'appel de la fonction.

Lorsque l'argument d'une fonction de traitement de séquences est écrit comme une simple chaîne de caractères, il devient une constante de type regclass. Puisqu'il ne s'agit que d'un OID, il permet de suivre la séquence originelle même en cas de renommage, changement de schéma... Ce principe de « lien fort » est en général souhaitable lors de références à la séquence dans les vues et valeurs par défaut de colonnes. Un « lien faible » est généralement souhaité lorsque la référence à la séquence est résolue à l'exécution. Ce comportement peut être obtenu en forçant le stockage des constantes sous la forme de constantes text plutôt que regclass :

                nextval('foo'::text)      foo est recherché à l'exécution

Le lien faible est le seul comportement accessible dans les versions de PostgreSQL™ antérieures à 8.1. Il peut donc être nécessaire de le conserver pour maintenir la sémantique d'anciennes applications.

L'argument d'une fonction de traitement de séquences peut être une expression ou une constante. S'il s'agit d'une expression textuelle, le transtypage implicite impose une recherche à l'exécution.

Les fonctions séquence disponibles sont :

nextval

Avance l'objet séquence à sa prochaine valeur et renvoie cette valeur. Ce fonctionnement est atomique : même si de multiples sessions exécutent nextval concurrentiellement, chacune obtient sans risque une valeur de séquence distincte.

Si un objet séquence a été créé avec les paramètres par défaut, les appels à nextval sur celui-ci renvoient des valeurs successives à partir de 1. D'autres comportements peuvent être obtenus en utilisant des paramètres spéciaux de la commande CREATE SEQUENCE(7) ; voir la page de référence de la commande pour plus d'informations.

[Important]

Important

Pour éviter le blocage de transactions concurrentes qui obtiennent des nombres de la même séquence, une opération nextval n'est jamais annulée ; c'est-à-dire qu'une fois la valeur récupérée, elle est considérée utilisée et ne sera jamais renvoyée de nouveau. Ceci est vrai même si la transaction appelante finit par demander son annulation ou si la requête appelant finit par ne pas utiliser la valeur. Par exemple, un INSERT doté d'une clause ON CONFLICT traitera la ligne à insérer, en incluant tout appel requis à nextval avant de détecter un conflit qui déclenchera la règle ON CONFLICT. De tels cas laisseront des valeurs inutilisées (des trous) dans la séquence de valeurs utilisées. De ce fait, les séquences proposées par PostgreSQLne peuvent pas être utilisées pour obtenir des séquences « sans trou ».

currval

Renvoie la valeur la plus récemment retournée par nextval pour cette séquence dans la session courante. (Une erreur est rapportée si nextval n'a jamais été appelée pour cette séquence dans cette session.) Parce qu'elle renvoie une valeur locale à la session, la réponse est prévisible, que d'autres sessions aient exécuté ou non la fonction nextval après la session en cours.

lastval

Renvoie la valeur la plus récemment retournée par nextval dans la session courante. Cette fonction est identique à currval, sauf qu'au lieu de prendre le nom de la séquence comme argument, elle se réfère à la dernière séquence utilisée par nextval dans la session en cours. Si nextval n'a pas encore été appelée dans la session en cours, un appel à lastval produit une erreur.

setval

Réinitialise la valeur du compteur de l'objet séquence. La forme avec deux paramètres initialise le champ last_value de la séquence à la valeur précisée et initialise le champ is_called à true, signifiant que le prochain nextval avance la séquence avant de renvoyer une valeur. La valeur renvoyée par currval est aussi configuré à la valeur indiquée. Dans la forme à trois paramètres, is_called peut être initialisé à true ou à false. true a le même effet que la forme à deux paramètres. Positionné à false, le prochain nextval retourne exactement la valeur indiquée et l'incrémentation de la séquence commence avec le nextval suivant. De plus, la valeur indiquée par currval n'est pas modifiée dans ce cas. Par exemple,

                  SELECT setval('foo', 42);           Le nextval suivant retourne 43
SELECT setval('foo', 42, true);     Comme ci-dessus
SELECT setval('foo', 42, false);    Le nextval suivant retourne 42

Le résultat renvoyé par setval est la valeur du second argument.

[Important]

Important

Comme les séquences sont non transactionnelles, les modifications réalisées par setval ne sont pas annulées si la transaction est annulée.

Si un objet séquence a été créé avec les paramètres par défaut, les appels à nextval sur celui-ci renvoient des valeurs successives à partir de 1. D'autres comportements peuvent être obtenus en utilisant des paramètres spéciaux de la commande CREATE SEQUENCE(7) ; voir la page de référence de la commande pour plus d'informations.

[Important]

Important

Pour éviter le blocage de transactions concurrentes qui obtiennent des nombres de la même séquence, une opération nextval n'est jamais annulée ; c'est-à-dire qu'une fois la valeur récupérée, elle est considérée utilisée, même si la transaction qui exécute nextval avorte par la suite. Cela signifie que les transactions annulées peuvent laisser des « trous » inutilisés dans la séquence des valeurs assignées. Les opérations setval ne sont jamais annulées non plus.