Chapitre 41. Interface de programmation serveur

Table des matières
41.1. Fonctions d'interface
SPI_connect -- connecter une procédure au gestionnaire SPI
SPI_finish -- déconnecter une procédure du gestionnaire SPI
SPI_exec -- exécute une commande
SPI_prepare -- prépare un plan pour une commande sans l'exécuter tout de suite
SPI_execp -- exécute le plan préparé par SPI_prepare
SPI_cursor_open -- met en place un curseur en utilisant un plan créé avec SPI_prepare
SPI_cursor_find -- recherche un curseur existant par nom
SPI_cursor_fetch -- extrait des lignes à partir d'un curseur
SPI_cursor_move -- déplace un curseur
SPI_cursor_close -- ferme un curseur
SPI_saveplan -- sauvegarde un plan
41.2. Fonctions de support d'interface
SPI_fname -- détermine le nom de colonne pour le numéro de colonne spécifié
SPI_fnumber -- détermine le numéro de colonne pour le nom de colonne spécifiée
SPI_getvalue -- renvoie la valeur de chaîne de la colonne spécifiée
SPI_getbinval -- retourne la valeur binaire de la colonne spécifiée
SPI_gettype -- retourne le nom du type de donnée de la colonne spécifiée
SPI_gettypeid -- retourne l'OID de type de donnée de la colonne spécifiée
SPI_getrelname -- retourne le nom de la relation spécifiée
41.3. Gestion de la mémoire
SPI_palloc -- alloue de la mémoire dans le contexte de mémoire courant
SPI_repalloc -- ré-alloue de la mémoire dans le contexte de mémoire courant
SPI_pfree -- libère de la mémoire dans le contexte de mémoire courant
SPI_copytuple -- effectue une copie d'une ligne dans le contexte de mémoire courant
SPI_copytupledesc -- effectue une copie du descripteur de ligne dans le contexte de mémoire courant
SPI_copytupleintoslot -- crée une copie d'une ligne et du descripteur dans le contexte de mémoire courant
SPI_modifytuple -- crée une ligne en remplaçant les champs sélectionnés d'une ligne donnée
SPI_freetuple -- libère une ligne allouée dans le contexte de mémoire courant
SPI_freetuptable -- libère une série de lignes créée par SPI_exec ou une fonction semblable
SPI_freeplan -- libère un plan sauvegardé auparavant
41.4. Visibilité des modifications de données
41.5. Exemples

L'interface de programmation serveur (SPI) donne aux auteurs de fonctions C la capacité de lancer des commandes SQL au sein de leurs fonctions. SPI est une série de fonctions d'interface simplifiant l'accès à l'analyseur, au planificateur, à l'optimiseur et au lanceur. SPI fait aussi de la gestion de mémoire.

Note : Les langages procéduraux disponibles donnent plusieurs moyens de lancer des commandes SQL à partir de procédures. Certains sont basés ou conçus à partir de SPI. Cette documentation présente donc également un intérêt pour les utilisateurs de ces langages.

Pour assurer la compréhension, nous utiliserons le terme de << fonction >> quand nous parlerons de fonctions d'interface SPI et << procédure >> pour une fonction C définie par l'utilisateur et utilisant SPI.

Notez que si, pendant l'exécution d'une procédure, la transaction est annulée du fait d'une erreur dans une commande, le contrôle ne sera pas rendu à votre procédure. Au lieu de cela, le travail sera annulé et le serveur attendra la commande suivante du client. À cela est lié une restriction, à savoir l'incapacité d'exécuter les instructions BEGIN, COMMIT et ROLLBACK (instructions de contrôle de transaction) au sein d'une procédure. Ces deux restrictions seront probablement modifiées dans le futur.

Les fonctions SPI renvoient un résultat positif en cas de succès (soit par une valeur de retour entière, soit dans la variable globale SPI_result comme décrit ci-dessous). En cas d'erreur, un résultat négatif ou NULL sera retourné.

Les fichiers de code source qui utilisent SPI doivent inclure le fichier d'en-tête executor/spi.h.

41.1. Fonctions d'interface

Table des matières
SPI_connect -- connecter une procédure au gestionnaire SPI
SPI_finish -- déconnecter une procédure du gestionnaire SPI
SPI_exec -- exécute une commande
SPI_prepare -- prépare un plan pour une commande sans l'exécuter tout de suite
SPI_execp -- exécute le plan préparé par SPI_prepare
SPI_cursor_open -- met en place un curseur en utilisant un plan créé avec SPI_prepare
SPI_cursor_find -- recherche un curseur existant par nom
SPI_cursor_fetch -- extrait des lignes à partir d'un curseur
SPI_cursor_move -- déplace un curseur
SPI_cursor_close -- ferme un curseur
SPI_saveplan -- sauvegarde un plan