9.12. Fonctions de manipulation de séquence

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

Tableau 9.34. 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
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 lors de l'appel à 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.12, « Types identifiant d'objet » pour plus d'informations sur regclass.

[Note]

Note

Avant la version 8.1 de PostgreSQL™, les arguments des fonctions de triatement de séquence é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. En revanche, 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équence 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 accesiible 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équence peut être une expression ou une constante. S'il s'agit d'une expression textuelle, le transtypage implicite implique une recherche lors à 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.

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 récupère la valeur de 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 avancera la séquence avant de renvoyer une valeur. Dans la forme à trois paramètres, is_called peut être initialisé à true ou à false. Positionné à false, le prochain nextval retourne exactement la valeur indiquée et l'incrémentation de la séquence commence avec le nextval suivant. Par exemple,

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

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

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 débutant à 1. D'autres comportements peuvent être obtenus en utilisant des paramètres spéciaux de la commande CREATE SEQUENCE ; 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écuta le nextval avorte par la suite. Ceci signifie que les transactions annulées pourraient laisser des « trous » inutilisés dans la séquence des valeurs assignées. Les opérations setval ne sont jamais annulées non plus.