DECLARE nom [ BINARY ] [ INSENSITIVE ] [ [ NO ] SCROLL ]
CURSOR [ { WITH | WITHOUT } HOLD ] FOR requête
[ FOR { READ ONLY | UPDATE [ OF colonnes [, ...] ] } ]
DECLARE permet à un utilisateur de créer des curseurs. Ils 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 au format texte ou au format binaire par l'utilisation de FETCH.
Les curseurs normaux renvoient des données au format texte, identique à celui produit par un SELECT . Les données sont stockées nativement au format binaire, le système doit donc effectuer une conversion pour produire le format texte. Une fois l'information arrivée au format texte, le client peut être amené à la convertir au format binaire pour la manipuler. De plus, les données au format texte sont souvent plus volumineuses qu'au format binaire. Les curseurs binaires renvoient les données dans une représentation binaire plus facilement manipulable. Néanmoins, pour afficher les données au format texte, les récupérer au format texte peut faciliter le travail du client.
Par exemple, dans le cas d'une requête renvoyant la valeur un extraite d'une colonne de type entier (integer), un curseur par défaut rend une chaîne 1 alors qu'un curseur binaire rend un champ de quatre octets qui contient la représentation interne de la valeur (dans l'ordre d'octets big-endian).
Les curseurs binaires doivent être utilisés avec précaution. Beaucoup d'applications, dont psql, ne sont pas préparées pour gérer des curseurs binaires et attendent le retour des données au format texte.
![[Note]](images/note.png)
Lorsque le client utilise le protocole de « requête étendue » pour exécuter une commande FETCH , le message du protocole Bind indique le format de récupération de la donnée. Ce choix surcharge la définition du curseur. Le concept de curseur binaire est alors rendu obsolète -- tout curseur peut être traité comme textuel ou binaire.
Le nom du curseur à créer.
Le curseur retourne les données au format binaire.
Les données récupérées à partir du curseur ne doivent pas être affectées par les mises à jour des tables concernées par le curseur tant que celui-ci existe. Dans PostgreSQL™, tous les curseurs sont inaltérables ; ce mot-clé n'a actuellement aucun effet. Il est présent pour des raisons de compatibilité avec le standard SQL.
SCROLL indique une utilisation possible du curseur pour récupérer des lignes de façon non séquentielle (c'est-à-dire en remontant la liste). En fonction de la complexité du plan d'exécution de la requête, SCROLL peut induire des pertes de performance sur le temps d'exécution de la requête. NO SCROLL indique que le curseur ne peut pas être utilisé pour récupérer des lignes de façon non séquentielle. La valeur par défaut autorise la non-séquentialité du curseur dans certains cas ; ce n'est pas la même chose que de spécifier SCROLL. Voir Notes pour les détails.
WITH HOLD (NDT : persistant) indique une utilisation possible du curseur après la validation de la transaction qui l'a créé. WITHOUT HOLD (NDT : volatil) interdit l'utilisation du curseur en dehors de la transaction qui l'a créé. WITHOUT HOLD est la valeur par défaut.
A SELECT or VALUES command which will provide the rows to be returned by the cursor.
FOR READ ONLY indique une utilisation du curseur en mode lecture seule. FOR UPDATE indique que le curseur est utilisé pour actualiser des tables. Comme les mises à jour de curseur ne sont pas supportées actuellement dans PostgreSQL™, FOR UPDATE provoque un message d'erreur, FOR READ ONLY est sans effet.
La (les) 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.
Si la clause WITH HOLD n'est pas précisée, le curseur créé par cette commande ne peut être utilisé qu'à l'intérieur d'une transaction. Ainsi, DECLARE sans WITH HOLD est inutile à l'extérieur d'un bloc de transaction : le curseur survivrait seulement jusqu'à la fin de l'instruction. PostgreSQL™ rapporte donc une erreur si cette commande est utilisée en dehors d'un bloc de transactions. On utilise BEGIN, COMMIT et ROLLBACK pour définir un bloc de transaction.
Si la clause WITH HOLD est précisée, et que la transaction qui a créé le curseur est validée, ce dernier reste accessible par les transactions ultérieures de la session. Au contraire, si la transaction initiale est annulée, le curseur est supprimé. Un curseur créé avec la clause WITH HOLD est fermé soit par un appel explicite à la commande CLOSE , soit par la fin de la session. Dans l'implantation actuelle, les lignes représentées par un curseur persistant (WITH HOLD) sont copiées dans un fichier temporaire ou en mémoire afin de garantir leur disponibilité pour les transactions suivantes.
L'option SCROLL est nécessaire à la définition de curseurs utilisés en récupération remontante (retour dans la liste des résultats, backward fetch), comme précisé par le standard SQL. Néanmoins, pour des raisons de compatibilité avec les versions antérieures, PostgreSQL™ autorise les récupérations remontantes sans que l'option SCROLL ne soit précisé, sous réserve que le plan d'exécution du curseur soit suffisamment simple pour être géré sans surcharge. Toutefois, il est fortement conseillé aux développeurs d'application ne pas utiliser les récupérations remontantes avec des curseurs qui n'ont pas été créés avec l'option SCROLL. Si NO SCROLL est spécifié, les récupérations remontantes sont toujours dévalidées.
Le standard SQL ne mentionne les curseurs que pour le SQL embarqué. PostgreSQL™ n'implante pas l'instruction OPEN pour les curseurs ; un curseur est considéré ouvert à sa déclaration. Néanmoins, ECPG, le préprocesseur de SQL embarqué pour PostgreSQL™, supporte les conventions du standard SQL relatives aux curseurs, dont celles utilisant les instructions DECLARE et OPEN .
Vous pouvez voir tous les curseurs disponibles en exécutant une requête sur la vue système pg_cursors .
Déclarer un curseur :
DECLARE liahona CURSOR FOR SELECT * FROM films;
Voir FETCH pour plus d'exemples sur l'utilisation des curseurs.
Le standard SQL n'autorise les curseurs que dans le SQL embarqué et dans les modules. PostgreSQL™ permet une utilisation interactive des curseurs.
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™.
DEALLOCATE
