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

30.3. Fonctions de commandes d'exécution

Une fois la connexion au serveur de la base de données établie avec succès, les fonctions décrites ici sont utilisées pour exécuter les requêtes SQL et les commandes.

30.3.1. Fonctions principales

PQexec

Soumet une commande au serveur et attend le résultat.

PGresult *PQexec(PGconn *conn, const char *command);

Renvoie un pointeur PGresult ou peut-être un pointeur NULL. Un pointeur non NULL sera généralement renvoyé sauf dans des conditions particulières comme un manque de mémoire ou lors d'erreurs sérieuses telles que l'incapacité à envoyer la commande au serveur. Si un pointeur NULL est renvoyé, il devrait être traité comme un résultat PGRES_FATAL_ERROR. Utilisez PQerrorMessage pour obtenir plus d'informations sur l'erreur.

Inclure plusieurs commandes SQL (séparées par des points virgules) dans la chaîne de commande est autorisé. Les requêtes multiples envoyées dans un simple appel à PQexec sont exécutées dans une seule transaction sauf si des commandes explicites BEGIN/COMMIT sont incluses dans la chaîne de requête pour la diviser dans de nombreuses transactions. Néanmoins, notez que la structure PGresult renvoyée décrit seulement le résultat de la dernière commande exécutée à partir de la chaîne. Si une des commandes doit échouer, l'exécution de la chaîne s'arrête et le PGresult renvoyé décrit la condition d'erreur.

PQexecParams

Soumet une commande au serveur et attend le résultat, avec la possibilité de passer des paramètres séparément du texte de la commande SQL.

PGresult *PQexecParams(PGconn *conn,
                       const char *command,
                       int nParams,
                       const Oid *paramTypes,
                       const char * const *paramValues,
                       const int *paramLengths,
                       const int *paramFormats,
                       int resultFormat);

PQexecParams est identique à PQexec mais offre des fonctionnalités supplémentaires : des valeurs de paramètres peuvent être spécifiées séparément de la chaîne de commande et les résultats de la requête peuvent être demandés soit au format texte soit au format binaire. PQexecParams est supporté seulement dans les connexions avec le protocole 3.0 et ses versions ultérieures ; elle échouera lors de l'utilisation du protocole 2.0.

Voici les arguments de la fonction :

conn

L'objet connexion où envoyer la commande.

command

La chaîne SQL à exécuter. Si les paramètres sont utilisés, ils sont référencés dans la chaîne avec $1, $2, etc.

nParams

Le nombre de paramètres fournis ; il s'agit de la longueur des tableaux paramTypes[], paramValues[], paramLengths[] et paramFormats[]. (Les pointeurs de tableau peuvent être NULL quand nParams vaut zéro.)

paramTypes[]

Spécifie, par OID, les types de données à affecter aux symboles de paramètres. Si paramTypes est NULL ou si tout élément spécifique du tableau est zéro, le serveur infère un type de donnée pour le symbole de paramètre de la même façon qu'il le ferait pour une chaîne litérale sans type.

paramValues[]

Spécifie les vraies valeurs des paramètres. Un pointeur nul dans ce tableau signifie que le paramètre correspondant est NULL ; sinon, le pointeur pointe vers une chaîne texte terminée par un octet nul (pour le format texte) ou vers des données binaires dans le format attendu par le serveur (pour le format binaire).

paramLengths[]

Spécifie les longueurs des données réelles des paramètres du format binaire. Il est ignoré pour les paramètres NULL et les paramètres de format texte. Le pointeur du tableau peut être NULL quand il n'y a pas de paramètres binaires.

paramFormats[]

Spécifie si les paramètres sont du texte (placez un zéro dans la ligne du tableau pour le paramètre correspondant) ou binaire (placez un un dans la ligne du tableau pour le paramètre correspondant). Si le pointeur du tableau est nul, alors tous les paramètres sont présumés être des chaînes de texte.

resultFormat

Indiquez zéro pour obtenir les résultats dans un format texte et un pour les obtenir dans un format binaire. (Il n'est actuellement pas possible d'obtenir des formats différents pour des colonnes de résultats différentes bien que le protocole le permette.)

Le principal avantage de PQexecParams sur PQexec est que les valeurs de paramètres pourraient être séparés à partir de la chaîne de commande, évitant ainsi le besoin de guillemets et d'échappements.

Contrairement à PQexec, PQexecParams autorise au plus une commande SQL dans une chaîne donnée (il peut y avoir des points-virgules mais pas plus d'une commande non vide). C'est une limitation du protocole sous-jacent mais cela a quelque utilité comme défense supplémentaire contre les attaques par injection de SQL.

[Astuce]

Astuce

Spécifier les types de paramètres via des OID est difficile, tout particulièrement si vous préférez ne pas coder en dur les valeurs OID particulières dans vos programmes. Néanmoins, vous pouvez éviter de le faire même dans des cas où le serveur lui-même ne peut pas déterminer le type du paramètre ou choisit un type différent de celui que vous voulez. Dans le texte de commande SQL, attachez une conversion explicite au symbole de paramètre pour montrer le type de données que vous enverrez. Par exemple :

SELECT * FROM ma_table WHERE x = $1::bigint;

Ceci impose le traitement du paramètre $1 en tant que bigint alors que, par défaut, il se serait vu affecté le même type que x. Forcer la décision du type de paramètre, soit de cette façon soit en spécifiant l'OID du type numérique, est fortement recommandé lors de l'envoi des valeurs des paramètres au format binaire car le format binaire a moins de redondance que le format texte et, du coup, il y a moins de chance que le serveur détecte une erreur de correspondance de type pour vous.

PQprepare

Soumet une requête pour créer une instruction préparée avec les paramètres donnés et attends la fin de son exécution.

PGresult *PQprepare(PGconn *conn,
        const char *stmtName,
        const char *query,
        int nParams,
        const Oid *paramTypes);

PQprepare crée une instruction préparée pour une exécution ultérieure avec PQexecPrepared. Cette fonction autorise les commandes utilisées de façon répété à être analysées et planifiées qu'une seule fois, plutôt qu'à chaque exécution. PQprepare est uniquement supporté par les connexions utilisant le protocole 3.0 et ses versions ultérieures ; elle échouera avec le protocole 2.0.

La fonction crée une instruction préparée nommée stmtName à partir de la chaîne query, devant contenir une seule commande SQL. stmtName pourrait être une chaîne vide pour créer une instruction non nommée, auquel cas toute instruction non nommée déjà existante est automatiquement remplacée par cette dernière. Une erreur sera rapportée si le nom de l'instruction est déjà définie dans la session en cours. Si des paramètres sont utilisés, ils sont référencés dans la requête avec $1, $2, etc. nParams est le nombre de paramètres pour lesquels des types sont prédéfinis dans le tableau paramTypes[] (le pointeur du tableau pourrait être NULL quand nParams vaut zéro). paramTypes[] spécifie les types de données à affecter aux symboles de paramètres par leur OID. Si paramTypes est NULL ou si un élément particulier du tableau vaut zéro, le serveur affecte un type de données au symbole du paramètre de la même façon qu'il le ferait pour une chaîne littérale non typée. De plus, la requête pourrait utiliser des symboles de paramètre avec des nombres plus importants que nParams ; les types de données seront aussi inférés pour ces symboles. (Voir PQdescribePrepared comme un moyen de trouver les types de données inférés.)

Comme avec PQexec, le résultat est normalement un objet PGresult dont le contenu indique le succès ou l'échec côté serveur. Un résultat NULL indique un manque de mémoire ou une incapacité à envoyer la commande. Utilisez PQerrorMessage pour obtenir plus d'informations sur de telles erreurs.

Les instructions préparées avec PQexecPrepared peuvent aussi être créées en exécutant les instructions SQL PREPARE. De plus, bien qu'il n'y ait aucune fonction libpq pour supprimer une instruction préparée, l'instruction SQL DEALLOCATE peut être utilisée dans ce but.

PQexecPrepared

Envoie une requête pour exécuter une instruction séparée avec les paramètres donnés, et attend le résultat.

PGresult *PQexecPrepared(PGconn *conn,
                         const char *stmtName,
                         int nParams,
                         const char * const *paramValues,
                         const int *paramLengths,
                         const int *paramFormats,
                         int resultFormat);

PQexecPrepared est identique à PQexecParams mais la commande à exécuter est spécifiée en nommant l'instruction préparée précédemment au lieu de donner une chaîne de requête. Cette fonctionnalité permet aux commandes utilisées de façon répétée d'être analysées et planifiées seulement une fois plutôt que chaque fois qu'ils sont exécutés. L'instruction doit avoir été préparée précédemment dans la session en cours. PQexecPrepared est supporté seulement dans les connexions du protocole 3.0 et ses versions ultérieures ; il échouera lors de l'utilisation du protocole 2.0.

Les paramètres sont identiques à PQexecParams, sauf que le nom d'une instruction préparée est donné au lieu d'une chaîne de requête et le paramètre paramTypes[] n'est pas présente (il n'est pas nécessaire car les types des paramètres de l'instruction préparée ont été déterminés à la création).

PQdescribePrepared

Soumet une requête pour obtenir des informations sur l'instruction préparée indiquée et attend le retour de la requête.

PGresult *PQdescribePrepared(PGconn *conn, const char *stmtName);

PQdescribePrepared permet à une application d'obtenir des informations sir une instruction préparée précédemment. PQdescribePrepared est seulement supporté avec des connexions utilisant le protocole 3.0 et ultérieures ; il échouera lors de l'utilisation du protocole 2.0.

stmtName peut être "" ou NULL pour référencer l'instruction non nommée. Sinon, ce doit être le nom d'une instruction préparée existante. En cas de succès, un PGresult est renvoyé avec le code retour PGRES_COMMAND_OK. Les fonctions PQnparams et PQparamtype peuvent utiliser ce PGresult pour obtenir des informations sur les paramètres d'une instruction préparée, et les fonctions PQnfields, PQfname, PQftype, etc fournissent des informations sur les colonnes résultantes (au cas où) de l'instruction.

PQdescribePortal

Soumet une requête pour obtenir des informations sur le portail indiqué et attend le retour de la requête.

PGresult *PQdescribePortal(PGconn *conn, const char *portalName);

PQdescribePortal permet à une application d'obtenir des informations sur un portail précédemment créé. (libpq ne fournit pas d'accès direct aux portails mais vous pouvez utiliser cette fonction pour inspecter les propriétés d'un curseur créé avec la commande SQL DECLARE CURSOR.) PQdescribePortal est seulement supporté dans les connexions via le protocole 3.0 et ultérieurs ; il échouera lors de l'utilisation du protocole 2.0.

portalName peut être "" ou NULL pour référencer un portail sans nom. Sinon, il doit correspondre au nom d'un portail existant. En cas de succès, un PGresult est renvoyé avec le code de retour PGRES_COMMAND_OK. Les fonctions PQnfields, PQfname, PQftype, etc peuvent utiliser ce PGresult pour obtenir des informations sur les colonnes résultats (au cas où) du portail.

La structure PGresult encapsule le résultat renvoyé par le serveur. Les développeurs d'applications libpq devraient faire attention au maintien de l'abstraction de PGresult. Utilisez les fonctions d'accès ci-dessous pour obtenir le contenu de PGresult. Évitez la référence aux champs de la structure PGresult car ils sont sujets à des changements dans le futur.

PQresultStatus

Renvoie l'état du résultat d'une commande.

ExecStatusType PQresultStatus(const PGresult *res);

PQresultStatus peut renvoyer une des valeurs suivantes :

PGRES_EMPTY_QUERY

La chaîne envoyée au serveur était vide.

PGRES_COMMAND_OK

Fin avec succès d'une commande ne renvoyant aucune donnée.

PGRES_TUPLES_OK

Fin avec succès d'une commande renvoyant des données (telle que SELECT ou SHOW).

PGRES_COPY_OUT

Début de l'envoi (à partir du serveur) d'un flux de données.

PGRES_COPY_IN

Début de la réception (sur le serveur) d'un flux de données.

PGRES_BAD_RESPONSE

La réponse du serveur n'a pas été comprise.

PGRES_NONFATAL_ERROR

Une erreur non fatale (une note ou un avertissement) est survenue.

PGRES_FATAL_ERROR

Une erreur fatale est survenue.

Si le statut du résultat est PGRES_TUPLES_OK, alors les fonctions décrites ci-dessous peuvent être utilisées pour récupérer les lignes renvoyées par la requête. Notez qu'une commande SELECT qui arrive à récupérer aucune ligne affichera toujours PGRES_TUPLES_OK. PGRES_COMMAND_OK est pour les commandes qui ne peuvent jamais renvoyer de lignes (INSERT, UPDATE, etc.). Une réponse PGRES_EMPTY_QUERY pourrait indiquer un bogue dans le logiciel client.

Un résultat de statut PGRES_NONFATAL_ERROR ne sera jamais renvoyé directement par PQexec ou d'autres fonctions d'exécution de requêtes ; les résultats de ce type sont passés à l'exécuteur de notifications (voir la Section 30.11, « Traitement des messages »).

PQresStatus

Convertit le type énuméré renvoyé par PQresultStatus en une constante de type chaîne décrivant le code d'état. L'appelant ne devrait pas libérer le résultat.

char *PQresStatus(ExecStatusType status);
PQresultErrorMessage

Renvoie le message d'erreur associé avec la commande ou une chaîne vide s'il n'y a pas eu d'erreurs.

char *PQresultErrorMessage(const PGresult *res);

S'il y a eu une erreur, la chaîne renvoyée incluera un retour chariot en fin. L'appelant ne devrait pas libérer directement le résultat. Il sera libéré quand la poignée PGresult associée est passée à PQclear.

Suivant immédiatement un appel à PQexec ou PQgetResult, PQerrorMessage (sur la connexion) renverra la même chaîne que PQresultErrorMessage (sur le résultat). Néanmoins, un PGresult conservera son message d'erreur jusqu'à destruction alors que le message d'erreur de la connexion changera lorsque des opérations suivantes seront réalisées. Utiliser PQresultErrorMessage quand vous voulez connaître le statut associé avec un PGresult particulier ; utilisez PQerrorMessage lorsque vous souhaitez connaître le statut à partir de la dernière opération sur la connexion.

PQresultErrorField

Renvoie un champ individuel d'un rapport d'erreur.

char *PQresultErrorField(const PGresult *res, int fieldcode);

fieldcode est un identifiant de champ d'erreur ; voir les symboles listés ci-dessous. NULL est renvoyé si PGresult n'est pas un résultat d'erreur ou d'avertissement, ou n'inclut pas le champ spécifié. Les valeurs de champ n'incluront normalement pas un retour chariot en fin. L'appelant ne devrait pas libérer directement le résultat. Il sera libéré quand la poignée PGresult associée est passée à PQclear.

Les codes de champs suivants sont disponibles :

PG_DIAG_SEVERITY

La sévérité ; le contenu du champ peut être ERROR, FATAL ou PANIC dans un message d'erreur, ou WARNING, NOTICE, DEBUG, INFO ou LOG dans un message de notification, ou une traduction localisée de ceux-ci. Toujours présent.

PG_DIAG_SQLSTATE

Le code SQLSTATE de l'erreur. Ce code identifie le type d'erreur qui est survenu ; il peut être utilisé par des interfaces qui réalisent les opérations spécifiques (telles que la gestion des erreurs) en réponse à une erreur particulière de la base de données. Pour une liste des codes SQLSTATE possibles, voir l'Annexe A, Codes d'erreurs de PostgreSQL. Ce champ n'est pas localisable et est toujours présent.

PG_DIAG_MESSAGE_PRIMARY

Le principal message d'erreur, compréhensible par un humain (typiquement sur une ligne). Toujours présent.

PG_DIAG_MESSAGE_DETAIL

Détail : un message d'erreur secondaire et optionnel proposant plus d'informations sur le problème. Pourrait être composé de plusieurs lignes.

PG_DIAG_MESSAGE_HINT

Astuce : une suggestion supplémentaire sur ce qu'il faut faire suite à ce problème. Elle a pour but de différer du détail car elle offre un conseil (potentiellement inapproprié) plutôt que des faits établis. Pourrait être composé de plusieurs lignes.

PG_DIAG_STATEMENT_POSITION

Une chaîne contenant un entier décimal indiquant le position du curseur d'erreur comme index dans la chaîne d'instruction originale. Le premier caractère se trouve à l'index 1 et les positions sont mesurées en caractères, et non pas en octets.

PG_DIAG_INTERNAL_POSITION

Ceci est défini de la même façon que le champ PG_DIAG_STATEMENT_POSITION mais c'est utilisé quand la position du curseur fait référence à une commande générée en interne plutôt qu'une soumise par le client. Le champ PG_DIAG_INTERNAL_QUERY apparaîtra toujours quand ce champ apparaît.

PG_DIAG_INTERNAL_QUERY

Le texte d'une commande échouée, générée en interne. Ceci pourrait être, par exemple, une requête SQL lancée par une fonction PL/pgSQL.

PG_DIAG_CONTEXT

Une indication du contexte dans lequel l'erreur est apparue. Actuellement, cela inclut une trace de la pile d'appels des fonctions actives de langages de procédures et de requêtes générées en interne. La trace a une entrée par ligne, la plus récente se trouvant au début.

PG_DIAG_SOURCE_FILE

Le nom du fichier contenant le code source où l'erreur a été rapportée.

PG_DIAG_SOURCE_LINE

Le numéro de ligne dans le code source où l'erreur a été rapportée.

PG_DIAG_SOURCE_FUNCTION

Le nom de la fonction dans le code source où l'erreur a été rapportée.

Le client est responsable du formatage des informations affichées suivant à ses besoins ; en particulier, il doit supprimer les longues lignes si nécessaires. Les caractères de retour chariot apparaissant dans les champs de message d'erreur devraient être traités comme des changements de paragraphes, pas comme des changements de lignes.

Les erreurs générées en interne par libpq auront une sévérité et un message principal mais aucun autre champ. Les erreurs renvoyées par un serveur utilisant un protocole antérieure à la 3.0 inclueront la sévérité, le message principal et, quelques fois, un message détaillé mais aucun autre champ.

Notez que les champs d'erreurs sont seulement disponibles pour les objets PGresult, et non pas pour les objets PGconn ; il n'existe pas de fonction PQerrorField.

PQclear

Libère le stockage associé avec un PGresult. Chaque résultat de commande devrait être libéré via PQclear lorsqu'il n'est plus nécessaire.

void PQclear(PGresult *res);

Vous pouvez conserver un objet PGresult aussi longtemps que vous en avez besoin ; il ne part pas lorsque vous lancez une nouvelle commande, même pas si vous fermez la connexion. Pour vous en débarrasser, vous devez appeler PQclear. En cas d'oubli, ceci résultera en des pertes mémoires pour votre application.

PQmakeEmptyPGresult

Construit un objet PGresult vide avec le statut donné.

PGresult* PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status);

Il s'agit d'une fonction interne de libpq pour allouer et initialiser un objet PGresult vide. Cette fonction renvoie NULL si la mémoire n'a pas pu être allouée. Il est exporté car certaines applications la trouvent utiles pour générer eux-même des objets résultats (particulièrement des objets avec des statuts d'erreur). Si conn n'est pas NULL et que status indique une erreur, le message d'erreur actuel pour la connexion spécifiée est copié dans PGresult. Notez que PQclear devrait éventuellement être appelé sur l'objet, comme avec un PGresult renvoyé par libpq elle-même.

30.3.2. Récupérer l'information provenant des résultats des requêtes

Ces fonctions sont utilisées pour extraire des informations provenant d'un objet PGresult représentant un résultat valide pour une requête (statut PGRES_TUPLES_OK). Ils peuvent aussi être utilisés pour extraire des informations à partir d'une opération Describe réussie : le résultat d'un Describe a les mêmes informations de colonnes qu'une exécution réelle de la requête aurait fournie, mais elle ne renvoie pas de lignes. Pour les objets ayant d'autres valeurs de statut, ces fonctions agiront comme si le résultat n'avait aucune ligne et aucune colonne.

PQntuples

Renvoie le nombre de lignes (tuples) du résultat de la requête. Comme elle envoie un entier, les gros ensembles de résultat pourraient dépasser la limite des valeurs renvoyées sur les systèmes d'exploitation 32 bits.

int PQntuples(const PGresult *res);
PQnfields

Renvoie le nombre de colonnes (champs) de chaque ligne du résultat de la requête.

int PQnfields(const PGresult *res);
PQfname

Renvoie le nom de la colonne associé avec le numéro de colonne donnée. Les numéros de colonnes commencent à zéro. L'appelant ne devrait pas libérer directement le numéro. Il sera libéré quand la poignée PGresult associée est passée à PQclear.

char *PQfname(const PGresult *res,
              int column_number);

NULL est renvoyé si le numéro de colonne est en dehors de la plage.

PQfnumber

Renvoie le numéro de colonne associé au nom de la colonne donné.

int PQfnumber(const PGresult *res,
              const char *column_name);

-1 est renvoyé si le nom donné ne correspond à aucune colonne.

Le nom donné est traité comme un identifiant dans une commande SQL, c'est-à-dire qu'il est mis en minuscule sauf s'il est entre des guillemets doubles. Par exemple, pour le résultat de la requête suivante

SELECT 1 AS FOO, 2 AS "BAR";

nous devons obtenir les résultats suivants :

PQfname(res, 0)              foo
PQfname(res, 1)              BAR
PQfnumber(res, "FOO")        0
PQfnumber(res, "foo")        0
PQfnumber(res, "BAR")        -1
PQfnumber(res, "\"BAR\"")    1
PQftable

Renvoie l'OID de la table à partir de laquelle la colonne donnée a été récupérée. Les numéros de colonnes commencent à zéro mais les colonnes des tables ont des numéros différents de zéro.

Oid PQftable(const PGresult *res,
             int column_number);

InvalidOid est renvoyé si le numéro de colonne est en dehors de la plage ou si la colonne spécifiée n'est pas une simple référence à une colonne de table, ou lors de l'utilisation d'un protocole antérieur à la version 3.0. Vous pouvez lancer des requêtes vers la table système pg_class pour déterminer exactement quelle table est référencée.

Le type Oid et la constante InvalidOid sera définie lorsque vous incluerez le fichier d'en-tête libpq. Ils auront le même type entier.

PQftablecol

Renvoie le numéro de colonne (à l'intérieur de la table) de la colonne correspondant à la colonne spécifiée de résultat de la requête. Les numéros de la colonne résultante commencent à 0.

int PQftablecol(const PGresult *res,
                int column_number);

Zéro est renvoyé si le numéro de colonne est en dehors de la plage, ou si la colonne spécifiée n'est pas une simple référence à une colonne de table, ou lors de l'utilisation d'un protocole antérieur à la version 3.0.

PQfformat

Renvoie le code de format indiquant le format de la colonne donné. Les numéros de colonnes commencent à zéro.

int PQfformat(const PGresult *res,
              int column_number);

Le code de format zéro indique une représentation textuelle des données alors qu'un code de format un indique une représentation binaire (les autres codes sont réservés pour des définitions futures).

PQftype

Renvoie le type de données associé avec le numéro de colonne donné. L'entier renvoyé est le numéro OID interne du type. Les numéros de colonnes commencent à zéro.

Oid PQftype(const PGresult *res,
            int column_number);

Vous pouvez lancer des requêtes sur la table système pg_type pour obtenir les noms et propriétés des différents types de données. Les OID des types de données intégrés sont définis dans le fichier src/include/catalog/pg_type.h de la distribution des sources.

PQfmod

Renvoie le modificateur de type de la colonne associée avec le numéro de colonne donné. Les numéros de colonnes commencent à zéro.

int PQfmod(const PGresult *res,
           int column_number);

L'interprétation des valeurs du modificateur est spécifique au type ; elles indiquent la précision ou les limites de taille. La valeur -1 est utilisée pour indiquer qu'« aucune information n'est disponible ». La plupart des types de données n'utilisent pas les modificateurs, auquel cas la valeur est toujours -1.

PQfsize

Renvoie la taille en octets de la colonne associée au numéro de colonne donné. Les numéros de colonnes commencent à zéro.

int PQfsize(const PGresult *res,
            int column_number);

PQfsize renvoie l'espace alloué pour cette colonne dans une ligne de la base de données, en d'autres termes la taille de la représentation interne du serveur du type de données (de façon cohérente, ce n'est pas réellement utile pour les clients). Une valeur négative indique que les types de données ont une longueur variable.

PQbinaryTuples

Renvoie 1 si PGresult contient des données binaires et 0 s'il contient des données texte.

int PQbinaryTuples(const PGresult *res);

Cette fonction est obsolète (sauf dans le cas d'une utilisation en relation avec COPY) car un seul PGresult peut contenir du texte dans certaines colonnes et des données binaires dans d'autres. PQfformat est la fonction préférée. PQbinaryTuples renvoie 1 seulement si toutes les colonnes du résultat sont dans un format binaire (format 1).

PQgetvalue

Renvoie la valeur d'un seul champ d'une seule ligne d'un PGresult. Les numéros de lignes et de colonnes commencent à zéro. L'appelant ne devrait pas libérer directement le résultat. Il sera libéré quand la poignée PGresult associée est passée à PQclear.

char* PQgetvalue(const PGresult *res,
                 int row_number,
                 int column_number);

Pour les données au format texte, la valeur renvoyée par PQgetvalue est une représentation au format chaîne de caractères terminée par un octet nul de la valeur du champ. Pour les données au format binaire, la valeur dans la représentation binaire est déterminée par le type de la donnée, fonctions typsend et typreceive (la valeur est en fait suivie d'un octet zéro dans ce cas aussi mais ce n'est pas réellement utile car la valeur a des chances de contenir d'autres valeurs NULL embarquées).

Une chaîne vide est renvoyée si la valeur du champ est NULL. Voir PQgetisnull pour distinguer les valeurs NULL des valeurs de chaîne vide.

Le pointeur renvoyé par PQgetvalue pointe vers le stockage qui fait partie de la structure PGresult. Personne ne devrait modifier les données vers lesquelles il pointe et tout le monde devrait copier explicitement les données dans un autre stockage s'il n'est pas utilisé après la durée de vie de la struture PGresult.

PQgetisnull

Teste un champ pour savoir s'il est nul. Les numéros de lignes et de colonnes commencent à zéro.

int PQgetisnull(const PGresult *res,
                int row_number,
                int column_number);

Cette fonction renvoie 1 si le champ est nul et 0 s'il contient une valeur non NULL (notez que PQgetvalue renverra une chaîne vide, et non pas un pointeur nul, pour un champ nul).

PQgetlength

Renvoie la longueur réelle de la valeur d'un champ en octet. Les numéros de lignes et de colonnes commencent à zéro.

int PQgetlength(const PGresult *res,
                int row_number,
                int column_number);

C'est la longueur réelle des données pour la valeur particulière des données, c'est-à-dire la taille de l'objet pointé par PQgetvalue. Pour le format textuel, c'est identique à strlen(). Pour le format binaire, c'est une information essentielle. Notez que personne ne devrait se fier à PQfsize pour obtenir la taille réelle des données.

PQnparams

Renvoie le nombre de paramètres d'une instruction préparée.

int PQnparams(const PGresult *res);

Cette fonction est seulement utile pour inspecter le résultat de PQdescribePrepared. Pour les autres types de requêtes, il renverra zéro.

PQparamtype

Renvoie le type de donnée du paramètre indiqué de l'instruction. Le numérotage des paramètres commence à 0.

Oid PQparamtype(const PGresult *res, int param_number);

Cette fonction est seulement utile pour inspecyer le résultat de PQdescribePrepared. Pour les autres types de requêtes, il renverra zéro.

PQprint

Affiche toutes les lignes et, optionnellement, les noms des colonnes dans le flux de sortie spécifié.

void PQprint(FILE* fout,      /* flux de sortie */
             const PGresult *res,
             const PQprintOpt *po);

typedef struct {
    pqbool  header;      /* affiche les en-têtes des champs et le nombre de
                            lignes */
    pqbool  align;       /* aligne les champs */
    pqbool  standard;    /* vieux format (mort) */
    pqbool  html3;       /* affiche les tables en HTML */
    pqbool  expanded;    /* étend les tables */
    pqbool  pager;       /* utilise le paginateur pour la sortie si nécessaire
                            */
    char    *fieldSep;   /* séparateur de champ */
    char    *tableOpt;   /* attributs des éléments de table HTML */
    char    *caption;    /* titre de la table HTML */
    char    **fieldName; /* Tableau terminé par un NULL des noms de remplacement
                            des champs */
} PQprintOpt;

Cette fonction était auparavant utilisée par psql pour afficher les résultats des requêtes mais ce n'est plus le cas. Notez qu'elle assume que les données sont dans un format textuel.

30.3.3. Récupérer les informations de résultats pour les autres commandes

Ces fonctions sont utilisées pour extraire des informations des objets PGresult qui ne sont pas les résultats d'instructions SELECT.

PQcmdStatus

Renvoie l'état de la commande depuis l'instruction SQL qui a généré le PGresult. L'appelant ne devrait pas libérer directement le résultat. Il sera libéré quand la poignée PGresult associée est passée à PQclear.

char * PQcmdStatus(PGresult *res);

D'habitude, c'est juste le nom de la commande mais elle pourrait inclure des données supplémentaires comme le nombre de lignes traitées.

PQcmdTuples

Renvoie le nombre de lignes affectées par la commande SQL.

char * PQcmdTuples(PGresult *res);

Cette fonction renvoie une chaîne contenant le nombre de lignes affectées par l'instruction SQL qui a généré PGresult. Cette fonction peut seulement être utilisée après l'exécution d'une instruction INSERT, UPDATE, DELETE, MOVE, FETCH ou COPY, ou EXECUTE avec une instruction préparée contenant une instruction INSERT, UPDATE ou DELETE. Si la commande qui a généré PGresult était autre chose, PQcmdTuples renverrait directement une chaîne vide. L'appelant ne devrait pas libérer la valeur de retour directement. Elle sera libérée quand la poignée PGresult associée est passée à PQclear.

PQoidValue

Renvoie l'OID de la ligne insérée, si la commande SQL était une instruction INSERT qui a inséré exactement une ligne dans une table comprenant des OID ou un EXECUTE d'une requête préparée contenant une instruction INSERT convenable. Sinon, cette fonction renvoie InvalidOid. Cette fonction renverra aussi InvalidOid si la table touchée par l'instruction INSERT ne contient pas d'OID.

Oid PQoidValue(const PGresult *res);
PQoidStatus

Renvoie une chaîne avec l'OID de la ligne insérée si la commande SQL était une instruction INSERT qui insère exactement une ligne, ou un EXECUTE d'une instruction préparée consistant en une commande INSERT (la chaîne sera 0 si l'instruction INSERT n'a inséré qu'une seule ligne ou si la table cible n'a pas d'OID). Si la commande n'était pas un INSERT, renvoie une chaîne vide.

char * PQoidStatus(const PGresult *res);

Cette fonction est obsolète et remplacée par PQoidValue. Elle n'est pas compatible avec les threads.

30.3.4. Chaîne d'échappement à inclure dans les commandes SQL

PQescapeStringConn échappe une chaîne à utiliser dans une commande SQL. Ceci est utile lors de l'insertion de valeurs comme constantes littérales. Certains caractères (tels que les guillemets et les antislashs) doivent être échappés pour les empêcher d'être interprétés spécialement par l'analyseur SQL. PQescapeStringConn réalise cette opération.

[Astuce]

Astuce

Il est tout particulièrement important de faire cet échappement proprement lors de la gestion de chaînes reçues d'une source non sûre. Sinon, il existe un risque de sécurité : vous êtes vulnérable à une attaque par « injection de SQL » où des commandes SQL non souhaitées remplissent votre base de données.

Notez qu'il n'est ni nécessaire ni correct de faire un échappement lorsque une valeur est passée comme paramètre séparé dans PQexecParams ou ses routines similaires.

size_t PQescapeStringConn (PGconn *conn,
                           char *to, const char *from, size_t length,
                           int *error);

PQescapeStringConn écrit une version échappée de la chaîne from dans le tampon to, en échappant les caractères spéciaux de façon à ce qu'ils ne puissent causer aucun problème, et en ajoutant un octet nul de terminaison. Les guillemets simples qui doivent entourer les chaînes PostgreSQL™ ne sont pas incluses dans la chaîne résultante ; ils doivent être fournis dans la commande SQL où le résultat sera inséré. Le paramètre from pointe le premier caractère d'une chaîne à protéger et le paramètre length donne le nombre d'octets dans cette chaîne. Un octet de terminaison, zéro, n'est pas requis et ne devrait pas être compté dans length (si un octet de terminaison est trouvé avant que length octets ne soient traités, PQescapeStringConn s'arrête au zéro ; le comportement ressemble donc à strncpy). to devrait pointer vers un tampon capable de contenir au moins un octet de plus que le double de la valeur de length, sinon le comportement est indéfini. Le comportement est indéfini si les chaînes to et from se surchargent.

Si le paramètre error n'est pas NULL, alors *error est initialisé à zéro en cas de succès et à une valeur différente de zéro dans le cas contraire. Actuellement, les seules conditions d'erreurs possibles impliquent un codage multi-octets invalide dans la chaîne en entrée. La chaîne en sortie est toujours générée en cas d'erreur mais il est probable que le serveur la rejettera en indiquant qu'elle est malformée. En cas d'erreur, un message adéquat est stocké dans l'objet conn, que error soit NULL ou non.

PQescapeString renvoie le nombre d'octets écrits dans to, sans inclure l'octet de terminaison.

size_t PQescapeString (char *to, const char *from, size_t length);

PQescapeString est une version obsolète de PQescapeStringConn ; la différence réside dans le fait qu'elle ne prend pas de paramètres conn ou error. À cause de ceci, elle ne peut ajuster son comportement suivant les propriétés de la connexion comme le codage des caractères et donc elle pourrait renvoyer des résultats faux. De plus, il n'existe aucun moyen de renvoyer les conditions de l'erreur.

PQescapeString peut être utilisé sereinement dans les programmes clients à un seul thread et fonctionnant avec une seule connexion PostgreSQL™ à la fois (dans ce cas, il peut trouver les informations qui l'intéressent « en arrière-plan »). Les autres contextes devraient être évités et PQescapeStringConn devrait être utilisé à la place.

30.3.5. Échapper des chaînes binaires pour une inclusion dans des commandes SQL

PQescapeByteaConn

Échappe des données binaires à utiliser à l'intérieur d'une commande SQL avec le type bytea. Comme avec PQescapeStringConn, c'est seulement utilisé pour insérer des données directement dans une chaîne de commande SQL.

unsigned char *PQescapeByteaConn(PGconn *conn,
                                 const unsigned char *from,
                                 size_t from_length,
                                 size_t *to_length);

Certaines valeurs d'octets doivent être échappées (mais toutes les valeurs d'octets peuvent être échappées) lorsqu'elles font partie d'un littéral bytea dans une instruction SQL. En général, pour échapper un octet, il est converti dans le nombre à trois chiffres correspondant à sa valeur octale et précédé habituellement par deux antislashs. Le guillemet simple et le caractère antislash ont des séquences d'échappements alternatives. Voir la Section 8.4, « Types de données binaires » pour plus d'informations. PQescapeByteaConn réalise cette opération en échappant seulement les octets requis.

Le paramètre from pointe sur le premier octet de la chaîne à échapper et le paramètre from_length donne le nombre d'octets de cette chaîne binaire (un octet zéro de terminaison n'est ni nécessaire ni compté). Le paramètre to_length pointe vers une variable qui contiendra la longueur de la chaîne échappée résultante. Cette longueur inclut l'octet zéro de terminaison.

PQescapeByteaConn renvoie une version échappée du paramètre from dans la mémoire allouée avec malloc(). Cette mémoire doit être libérée avec PQfreemem lorsque le résultat n'est plus nécessaire. Tous les caractères spéciaux de la chaîne de retour sont remplacés de façon à ce qu'ils puissent être traités proprement par l'analyseur de chaînes littérales de PostgreSQL™ et par l'entrée bytea de la fonction. Un octet zéro de terminaison est aussi ajouté. Les guillemets simples qui englobent les chaînes littérales de PostgreSQL™ ne font pas partie de la chaîne résultante.

En cas d'erreur, un pointeur NULL est renvoyé et un message d'erreur adéquat est stocké dans l'objet conn. Actuellement, la seule erreur possible est une mémoire insuffisante pour stocker la chaîne résultante.

PQescapeBytea

PQescapeBytea est une version obsolète de PQescapeByteaConn.

unsigned char *PQescapeBytea(const unsigned char *from,
                             size_t from_length,
                             size_t *to_length);

La seule différence avec PQescapeByteaConn est que PQescapeBytea ne prend pas de paramètre PGconn. À cause de ceci, il ne peut ajuster son comportement suivant les propriétés de la connexion (en particulier si les chaînes conformes au standard sont activées) et, du coup, il pourrait donner de mauvais résultats. De plus, il n'a aucun moyen de renvoyer un message d'erreur en cas d'échec.

PQescapeBytea peut être utilisé en toute sécurité dans les programmes clients avec un seul thread et fonctionnant avec une seule connexion PostgreSQL™ en même temps (dans ce cas, il peut trouver ce dont il a besoin de savoir « en arrière-plan »). Dans d'autres contextes, il devrait être remplacé par PQescapeByteaConn.

PQunescapeBytea

Convertit une représentation de la chaîne en donnés binaires -- l'inverse de PQescapeBytea. Ceci est nécessaire lors de la récupération de données bytea en format texte, mais pas lors de sa récupération au format binaire.

unsigned char *PQunescapeBytea(const unsigned char *from, size_t *to_length);

Le paramètre from pointe vers une chaîne de telle façon qu'elle pourrait provenir de PQgetvalue lorsque la colonne est de type bytea. PQunescapeBytea convertit cette représentation de la chaîne en sa représentation binaire. Elle renvoie un pointeur vers le tampon alloué avec malloc(), ou NULL en cas d'erreur, et place la taille du tampon dans to_length. Le résultat doit être libéré en utilisant PQfreemem lorsque celui-ci n'est plus nécessaire.

Cette conversion n'est pas l'inverse exacte de PQescapeBytea car la chaîne n'est pas échappée avec PQgetvalue. Cela signifie en particulier qu'il n'y a pas besoin de réfléchir à la mise entre guillemets de la chaîne, et donc pas besoin d'un paramètre PGconn.

PQfreemem

Libère la mémoire allouée par libpq.

void PQfreemem(void *ptr);

Libère la mémoire allouée par libpq, particulièrement PQescapeByteaConn, PQescapeBytea, PQunescapeBytea, et PQnotifies. Il est particulièrement important que cette fonction soit utilisée sur Microsoft Windows à la place de free(). Ceci est dû au fait qu'une allocation de mémoire dans une DLL et à sa libération dans l'application ne fonctionne que si les options multithread/monothread, release/debug et statique/dynamique sont identiques pour la DLL et pour l'application. Sur les autres plateformes que Microsoft Windows, cette fonction est identique à celle de la bibliothèque standard, free().