DECLARE

Nom

DECLARE -- définit un curseur

Synopsis

DECLARE nom [ BINARY ] [ INSENSITIVE ] [ [ NO ] SCROLL ]
    CURSOR [ { WITH | WITHOUT } HOLD ] FOR requête
    [ FOR { READ ONLY | UPDATE [ OF colonnes [, ...] ] } ]

Description

DECLARE autorise un utilisateur à créer des curseurs qui peuvent être utilisés pour récupérer un petit nombre de lignes à la fois à partir d'une requête plus importante. Les curseurs peuvent renvoyer des données soit au format texte soit au format binaire en utilisant FETCH.

Les curseurs normaux renvoient des données au format texte, le même qu'un SELECT produirait. Quand des données sont stockées nativement dans le format binaire, le système doit faire une conversion pour produire le format texte. Une fois que l'information revient au format texte, l'application cliente pourrait avoir besoin de la convertir en un format binaire pour la manipuler. De plus, des données au format texte sont souvent plus importantes qu'au format binaire. Les curseurs binaires renvoient les données dans une représentation binaire qui pourrait être plus facilement manipulée. Néanmoins, si vous avez l'intention d'afficher les données en texte, le récupérer au format texte vous épargnera quelques efforts du côté client.

En tant qu'exemple, si une requête renvoie  une valeur de 1 appartenant à une colonne entier, vous voudriez obtenir une chaîne de 1 avec un curseur par défaut alors qu'avec un curseur binaire, vous voudriez obtenir un champ de quatre octets contenant la représentation interne de la valeur (dans l'ordre d'octets big-endian).

Des curseurs binaires devraient être utilisés avec attention. Beaucoup d'applications, incluant psql, ne sont pas préparées pour gérer des curseurs binaires et pour un retour des données au format texte.

Note : Quand l'application cliente utilise le protocole de << requête étendue >> pour lancer une commande FETCH, le message du protocole Bind spécifie quel donnée est à récupérer au format texte ou binaire. Ce choix surcharge la façon dont le curseur est défini. Le concept d'un curseur binaire en tant que tel est du coup obsolète lors de l'utilisation du protocole de requête étendue --- tout curseur peut être traité soit en texte soit en binaire.

Paramètres

nom

Le nom du curseur à créer.

BINARY

Fait que le curseur renvoie des données au format binaire plutôt qu'au format texte.

INSENSITIVE

Indique que les données récupérées à partir du curseur devraient être non affectées par les mises à jour des tables sous-jacentes au curseur tant que celui-ci existe. Dans PostgreSQL, tous les curseurs sont insensibles ; cet mot clé n'a actuellement aucun effet et est présent pour la compatibilité avec le standard SQL.

SCROLL
NO SCROLL

SCROLL spécifie que le curseur pourrait être utilisé pour récupérer des lignes de façon non séquentielle (c'est-à-dire en arrière). Suivant la complexité du plan d'exécution de la requête, spécifier SCROLL pourrait imposer des pertes de performance sur le temps d'exécution de la requête. NO SCROLL spécifie que le curseur ne peut pas être utilisé pour récupérer des lignes d'une façon non séquentielle.

WITH HOLD
WITHOUT HOLD

WITH HOLD spécifie que le curseur peut continuer à être utilisé après que la transaction qui l'a créé ait été validée avec succès. WITHOUT HOLD spécifie que le curseur ne peut être utilisé en dehors de la transaction qui l'a créé. Si ni WITHOUT HOLD ni WITH HOLD n'est spécifié, WITHOUT HOLD est la valeur par défaut.

requête

Une commande SELECT qui fournira les lignes à renvoyer par le curseur. Référez-vous à SELECT pour plus d'informations sur les requêtes valides.

FOR READ ONLY
FOR UPDATE

FOR READ ONLY indique que le curseur sera utilisé en mode lecture seule. FOR UPDATE indique que le curseur sera utilisé pour mettre à jour des tables. Comme les mises à jour de curseur ne sont pas supportées actuellement dans PostgreSQL, spécifier FOR UPDATE causera un message d'erreur et spécifier FOR READ ONLY n'aura pas d'effet.

colonnes

Colonne(s) à mettre à jour par le curseur. Comme les mises à jour de curseur ne sont actuellement pas supportées dans PostgreSQL, la clause FOR UPDATE provoque un message d'erreur.

Les mots clés BINARY, INSENSITIVE et SCROLL peuvent apparaître dans n'importe quel ordre.

Notes

Sauf si WITH HOLD est spécifié, le curseur créé par cette commande peut seulement être utilisée à l'intérieur d'une transaction. Du coup, DECLARE sans WITH HOLD est inutile à l'extérieur d'un bloc de transaction : le curseur survivrait seulement jusqu'à la fin de l'instruction. Du coup, PostgreSQL rapporte une erreur si cette commande est utilisée en dehors d'un bloc de transaction. Utilisez BEGIN, COMMIT et ROLLBACK pour définir un bloc de transaction.

Si WITH HOLD est spécifié et que la transaction créant le curseur valide avec accès, le curseur peut continuer à être accédé par les transactions suivantes pour la même session. (Mais si la transaction l'ayant créé est annulée, le curseur est supprimé.) Un curseur créé avec WITH HOLD est fermé quand une commande CLOSE explicite est lancée sur lui ou quand la session se termine. Dans l'implémentation actuelle, les lignes représentées par un curseur détenu sont copiées dans un fichier temporaire ou dans une partie de la mémoire pour qu'elles restent disponibles pour les transactions suivantes.

L'option SCROLL devrait être spécifiée lors de la création d'un curseur qui sera utilisé avec des récupérations inverses. Ceci est requis par le standard SQL. Néanmoins, pour la compatibilité avec les anciennes versions, PostgreSQL autorisera les récupérations en arrière sans SCROLL, si le plan de requête du curseur est assez simple pour qu'aucune surcharge ne soit nécessaire pour le supporter. Néanmoins, les développeurs d'applications sont avertis de ne pas se fier sur l'utilisation de recherche en arrière à partir de curseurs qui n'ont pas été créés avec SCROLL. Si NO SCROLL est spécifié, alors les recherches inverses sont interdites dans tous les cas.

Le standard SQL fait seulement quelques réserves pour les curseurs dans le SQL embarqué. Le serveur PostgreSQL n'implémente pas l'instruction OPEN pour les curseurs ; un curseur est considéré ouvert à sa déclaration. Néanmoins, ECPG, le préprocesseur SQL embarqué pour PostgreSQL, supporte les conventions des curseurs du SQL standard, incluant ceux impliquant les instructions DECLARE et OPEN.

Exemples

Pour déclarer un curseur :

DECLARE liahona CURSOR FOR SELECT * FROM films;

Voir FETCH pour plus d'exemples sur l'utilisation des curseurs.

Compatibilité

Le standard SQL autorise les curseurs uniquement dans du SQL embarqué et dans des modules. PostgreSQL permet aux curseurs d'être utilisés interactivement.

Le standard SQL autorise les curseurs à mettre à jour les données d'une table. Tous les curseurs PostgreSQL sont en lecture seule.

Les curseurs binaires sont une extension PostgreSQL.