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.
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.
La fonction PQresultStatus
devrait être appelée pour
vérifier le code retour pour toute erreur (incluant la valeur d'un
pointeur NULL, auquel cas il renverra PGRES_FATAL_ERROR
).
Utilisez PQerrorMessage
pour obtenir plus
d'informations sur l'erreur.
La chaîne de la commande peut inclure plusieurs commandes SQL (séparées par des points
virgules). Les requêtes multiples envoyées
dans un unique appel à PQexec
sont exécutées dans une seule
transaction, sauf si des commandes BEGIN
/COMMIT
explicites sont incluses dans la chaîne
de requête pour la diviser en de multiples transactions. (Voir Section 55.2.2.1 pour plus de détails sur comment le
serveur traite les chaînes multi-requêtes.) Notez néanmoins
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 échoue, 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.
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 littérale sans type.
paramValues[]
Spécifie les vraies valeurs des paramètres. Un pointeur NULL 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 (place un 0 dans la ligne du tableau pour le paramètre correspondant) ou binaire (place un 1 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.
Les valeurs passées dans le format binaire nécessitent de connaître la
représentation interne attendue par le processus backend. Par exemple, les entiers
doivent être passés dans l'ordre réseau pour les octets. Passer des
valeurs numeric
requiert de connaître le format de stockage
du serveur, comme implémenté dans
src/backend/utils/adt/numeric.c::numeric_send()
et
src/backend/utils/adt/numeric.c::numeric_recv()
.
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 peuvent être
séparées à partir de la chaîne de commande, évitant ainsi le besoin
de guillemets et d'échappements, toujours pénibles et sources d'erreurs.
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.
Spécifier les types de paramètres via des OID est difficile, surtout si vous préférez ne pas coder en dur des 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 la commande SQL, ajoutez une conversion explicite au symbole de paramètre pour indiquer 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 à être exécutées de façon répétée sans
être analysées et planifiées à chaque fois ; voir PREPARE pour les détails.
La fonction crée une instruction préparée nommée stmtName
à partir de la chaîne query
,
qui ne doit contenir qu'une seule commande SQL.
stmtName
peut être ""
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
sinon une erreur sera levé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 peut 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
pour 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.
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
que le paramètre paramTypes[]
n'est pas présent (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 sur une instruction préparée précédente.
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 de l'instruction préparée, et les fonctions
PQnfields
, PQfname
,
PQftype
, etc. fournissent des informations sur les colonnes
résultantes (s'il y en a) 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
en 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ésultantes (s'il y en a) 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 de référencer directement les champs de la structure PGresult
car ils sont sujets à 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.
PGRES_COPY_BOTH
#Lancement du transfert de données Copy In/Out (vers et à partir du serveur). Cette fonctionnalité est seulement utilisée par la réplication en flux, ce statut ne devrait donc pas apparaître dans les applications ordinaires.
PGRES_SINGLE_TUPLE
#
La structure PGresult
contient une seule
ligne de résultat provenant de la commande courante. Ce statut
n'intervient que lorsque le mode ligne-à-ligne a été sélectionné
pour cette requête (voir Section 34.6).
PGRES_PIPELINE_SYNC
#
La structure PGresult
représente
un point de synchronisation dans le mode pipeline, réclamé par
PQpipelineSync
.
Ce statut survient seulement quand le mode pipeline a été
sélectionné.
PGRES_PIPELINE_ABORTED
#
La structure PGresult
représente un
pipeline qui a reçu une erreur du serveur.
PQgetResult
doit être appelé de façon répété
et, chaque fois, il renverra ce code de statut jusqu'à la fin du
pipeline courant, auquel cas il renverra
PGRES_PIPELINE_SYNC
et le traitement normal
pourra recommencer.
Si le statut du résultat est PGRES_TUPLES_OK
ou PGRES_SINGLE_TUPLE
, 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
récupère zéro ligne affichera toujours
PGRES_TUPLES_OK
. PGRES_COMMAND_OK
est
pour les commandes qui ne peuvent jamais renvoyer de lignes
(INSERT
ou UPDATE
sans une clause RETURNING
, 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 34.13).
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
le pointeur PGresult
associé sera passé à
PQclear
.
Immédiatement après 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 avec les opérations suivantes. Utilisez
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.
PQresultVerboseErrorMessage
#
Renvoie une version reformatée du message d'erreur associé avec un objet
PGresult
.
char *PQresultVerboseErrorMessage(const PGresult *res, PGVerbosity verbosity, PGContextVisibility show_context);
Dans certaines situations, un client pourrait vouloir une
version plus détaillée d'une erreur déjà rapportée.
PQresultVerboseErrorMessage
couvre ce besoin en
traitant le message tel qu'il aurait été produit par
PQresultErrorMessage
si la configuration souhaitée
de la verbosité était activée pour la connexion au moment où l'objet
PGresult
indiqué a été généré. Si le
PGresult
ne correspond pas une erreur,
« PGresult is not an error result » est renvoyé à la place.
La chaîne renvoyée inclut un retour à la ligne en fin de chaîne.
Contrairement à la plupart des autres fonctions d'extraction de données
à partir d'un objet PGresult
, le résultat de
cette fonction est une chaîne tout juste allouée. L'appelant doit la
libérer en utilisant PQfreemem()
quand la chaîne
n'est plus nécessaire.
Un NULL en retour est possible s'il n'y a pas suffisamment de mémoire.
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 le pointeur
PGresult
associé sera passé à
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 d'un de ceux-ci. Toujours présent.
PG_DIAG_SEVERITY_NONLOCALIZED
#
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). C'est
identique au champ PG_DIAG_SEVERITY
sauf que le
contenu n'est jamais traduit. Il est présent uniquement dans les
rapports générés par les versions 9.6 et ultérieurs de
PostgreSQL.
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 utilisateur pour des 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. Ce champ n'est pas localisable et est toujours présent.
PG_DIAG_MESSAGE_PRIMARY
#Le message d'erreur principal, 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 courir sur 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 courir sur plusieurs lignes.
PG_DIAG_STATEMENT_POSITION
#Une chaîne contenant un entier décimal indiquant une position du curseur d'erreur comme index dans la chaîne d'instruction originale. Le premier caractère a l'index 1 et les positions sont mesurées en caractères, et non en octets.
PG_DIAG_INTERNAL_POSITION
#
Ceci est défini de la même façon que le champ PG_DIAG_STATEMENT_POSITION
mais 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 générée en interne et échouée. Ce 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 du langage procédural actif et de requêtes générées en interne. La trace a une entrée par ligne, la plus récente au début.
PG_DIAG_SCHEMA_NAME
#Si l'erreur était associée à un objet spécifique de la base de données, nom du schéma contenant cet objet.
PG_DIAG_TABLE_NAME
#Si l'erreur était associée à une table spécifique, nom de cette table. (Fait référence au champ du nom du schéma pour le nom du schéma de la table.)
PG_DIAG_COLUMN_NAME
#Si l'erreur était associée à une colonne spécifique d'une table, nom de cette colonne. (Fait référence aux champs de noms du schéma et de la table pour identifier la table.)
PG_DIAG_DATATYPE_NAME
#Si l'erreur était associée à un type de données spécifique, nom de ce type de données. (Fait référence au champ du nom du schéma pour le schéma du type de données.)
PG_DIAG_CONSTRAINT_NAME
#Si l'erreur était associée à une contrainte spécifique, nom de cette contrainte. Cela fait référence aux champs listés ci-dessus pour la table ou le domaine associé. (Dans ce cadre, les index sont traités comme des contraintes, même s'ils n'ont pas été créés avec la syntaxe des contraintes.)
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.
Les champs pour les noms du schéma, de la table, de la colonne, du type de données et de la contrainte sont fournis seulement pour un nombre limité de types d'erreurs ; voir Annexe A. Ne supposez pas que la présence d'un de ces champs garantisse la présence d'un autre champ. Les sources d'erreurs du moteur observent les relations notées ci-dessus mais les fonctions utilisateurs peuvent utiliser ces champs d'une autre façon. Dans la même idée, ne supposez pas que ces champs indiquent des objets encore existants dans la base de données courante.
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.
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);
Si l'argument est un pointeur NULL
, aucune opération
n'est réalisée.
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, le résultat sera une
fuite de mémoire dans votre application.
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
ou
PGRES_SINGLE_TUPLE
). Elles 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 avec zéro ligne.
Pour les objets avec d'autres valeurs de statut, ces fonctions agiront comme
si le résultat avait zéro ligne et zéro colonne.
PQntuples
#
Renvoie le nombre de lignes (enregistrements, ou
tuples) du résultat de la requête.
(Notez que les objets PGresult
sont limités à
au plus INT_MAX
lignes, donc un résultat de type
int
est suffisant.)
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 résultat. Il sera libéré quand le pointeur
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 à 0.
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. Vous pouvez requêter la table
système pg_class
pour déterminer exactement quelle
table est référencée.
Le type Oid
et la constante
InvalidOid
seront définis lorsque vous incluerez le
fichier d'en-tête libpq. Ils auront le même
type entier.
PQftablecol
#Renvoie le numéro de colonne (dans sa table) de la colonne correspondant à la colonne spécifiée de résultat de la requête. Les numéros de colonne du résultat commencent à 0, mais les colonnes de table ont des numéros supérieurs à zéro.
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 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
catalog/pg_type_d.h
du répertoire
include
de l'installation de
PostgreSQL.
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 ; typiquement elles indiquent la précision ou les limites de taille. La valeur -1 est utilisée pour indiquer « aucune information 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 à 0.
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 (en conséquence 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 à préférer. 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 le pointeur
PGresult
associé sera passé à
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
chaînes vides.
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 les données dans un autre stockage explicitement si elles
doivent être utilisées après la durée de vie de la structure
PGresult
.
PQgetisnull
#Teste un champ pour savoir s'il est NULL. Les numéros de lignes et de colonnes commencent à 0.
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 NULL, pour un champ NULL).
PQgetlength
#Renvoie la longueur réelle de la valeur d'un champ en octet. Les numéros de lignes et de colonnes commencent à 0.
int PQgetlength(const PGresult *res, int row_number, int column_number);
C'est la longueur réelle des données pour cette donnée en particulier,
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 l'on ne devrait
pas 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 utile seulement pour inspecter le résultat de
PQdescribePrepared
. Pour les autres types de
résultats, elle renverra zéro.
PQparamtype
#Renvoie le type de donnée du paramètre indiqué dans l'instruction. Les numéros des paramètres commencent à 0.
Oid PQparamtype(const PGresult *res, int param_number);
Cette fonction est utile seulement pour inspecter le résultat de
PQdescribePrepared
. Pour les autres types de
résultats, elle 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.
Ces fonctions sont utilisées pour extraire d'autres informations des objets
PGresult
.
PQcmdStatus
#
Renvoie l'état de la commande de l'instruction SQL qui a généré le
PGresult
.
char * PQcmdStatus(PGresult *res);
D'habitude, c'est juste le nom de la commande mais elle peut inclure des
données supplémentaires comme le nombre de lignes traitées.
L'appelant ne devrait pas libérer directement le résultat. Il sera libéré
quand le pointeur PGresult
associée sera passé à
PQclear
.
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 ne peut être utilisée
qu'après l'exécution d'une instruction SELECT
,
CREATE TABLE AS
, INSERT
,
UPDATE
, DELETE
,
MERGE
, MOVE
,
FETCH
ou COPY
, ou un
EXECUTE
d'une instruction préparée contenant une
instruction INSERT
, UPDATE
,
DELETE
ou MERGE
. 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 le pointeur PGresult
associée
sera passé à PQclear
.
PQoidValue
#
Renvoie l'OID de la ligne insérée, si la commande
SQL était un
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
#
Cette fonction est obsolète. Utilisez plutôt
PQoidValue
. De plus, elle n'est pas compatible
avec les threads. Elle renvoie une chaîne contenant l'OID de la
ligne insérée alors que PQoidValue
renvoie
la valeur de l'OID.
char * PQoidStatus(const PGresult *res);
PQescapeLiteral
#
char *PQescapeLiteral(PGconn *conn, const char *str, size_t length);
PQescapeLiteral
échappe une chaîne pour l'utiliser
dans une commande SQL. C'est utile pour insérer des données comme des
constantes dans des commandes SQL. Certains caractères, comme les
guillemets et les antislashs, doivent être traités avec des caractères
d'échappement pour éviter qu'ils ne soient traités d'après leur
signification spéciale par l'analyseur SQL.
PQescapeLiteral
réalise cette opération.
PQescapeLiteral
renvoie une version échappée du
paramètre str
dans une mémoire allouée avec
malloc()
. Cette mémoire devra être libérée en
utilisant PQfreemem()
quand le résultat ne sera
plus utile. Un octet zéro final n'est pas requis et ne doit pas être
compté dans length
. (Si un octet zéro est
découvert avant le traitement de length
octets,
PQescapeLiteral
s'arrête au zéro ; ce
comportement est celui de strncpy
.) Les
caractères spéciaux de la chaîne en retour ont été remplacés pour qu'ils
puissent être traités correctement par l'analyseur de chaînes de
PostgreSQL. Un octet zéro final est aussi
ajouté. Les guillemets simples qui doivent entourer les chaînes littérales
avec PostgreSQL sont inclus dans la chaîne
résultante.
En cas d'erreur,
PQescapeLiteral
renvoit
NULL
et
un message adéquat est stocké dans l'objet
conn
.
Il est particulièrement important de faire un échappement propre lors de l'utilisation de chaînes provenant d'une source qui n'est pas de confiance. Sinon, il existe un risque de sécurité : vous vous exposez à une attaque de type « injection SQL » avec des commandes SQL non voulues injectées dans votre base de données.
Notez qu'il n'est pas nécessaire ni correct de faire un échappement quand
une valeur est passée en tant que paramètre séparé dans
PQexecParams
ou ses routines sœurs.
PQescapeIdentifier
#
char *PQescapeIdentifier(PGconn *conn, const char *str, size_t length);
PQescapeIdentifier
échappe une chaîne pour qu'elle
puisse être utilisé en tant qu'identifiant SQL, par exemple pour le
nom d'une table, d'une colonne ou d'une fonction. C'est utile quand un
identifiant fourni par un utilisateur pourrait contenir des caractères
spéciaux, qui sinon ne seraient pas interprétés comme faisant
partie de l'identifiant par l'analyseur SQL, ou lorsque l'identifiant
pourrait contenir des caractères en majuscule, dont la casse doit
être préservée.
PQescapeIdentifier
renvoit une version du paramètre
str
échappée comme doit l'être un identifiant SQL,
dans une mémoire allouée avec malloc()
. Cette
mémoire doit être libérée en utilisant PQfreemem()
quand le résultat n'est plus nécessaire. Un octet zéro final n'est pas
nécessaire et ne doit pas être comptabilisé dans
length
. (Si un octet zéro est trouvé avant
le traitement de length
octets,
PQescapeIdentifier
s'arrête au zéro ; ce
comportement est celui de strncpy
.) Les
caractères spéciaux de la chaîne en retour ont été remplacés pour que
ce dernier soit traité proprement comme un identifiant SQL. Un octet
zéro final est aussi ajouté. La chaîne de retour sera aussi entourée de
guillemets doubles.
En cas d'erreur,
PQescapeIdentifier
renvoit
NULL
et
un message d'erreur adéquat est stocké dans l'objet
conn
.
Comme avec les chaînes littérales, pour empêcher les attaques par injection SQL, les identifiants SQL doivent être échappés lorsqu'ils proviennent d'une source non sûre.
PQescapeStringConn
#
size_t PQescapeStringConn (PGconn *conn, char *to, const char *from, size_t length, int *error);
PQescapeStringConn
> échappe les chaînes littérales de
la même façon que
PQescapeLiteral
. Contrairement à
PQescapeLiteral
, l'appelant doit fournir un tampon
d'une taille appropriée. De plus,
PQescapeStringConn
>
n'ajoute pas de guillemets simples autour des chaînes littérales de
PostgreSQL ; elles doivent être ajoutées
dans la commande SQL où ce résultat sera inséré. Le paramètre
from
pointe vers le premier caractère de la chaîne
à échapper, et le paramètre length
précise le
nombre d'octets contenus dans cette chaîne. Un octet zéro final n'est
pas nécessaire et ne doit pas être comptabilisé dans
length
. (Si un octet zéro est trouvé avant
le traitement de length
octets,
PQescapeStringConn
s'arrête au zéro ; ce
comportement est celui de strncpy
.)
to
doit pointer vers un tampon qui peut contenir
au moins un octet de plus que deux fois la valeur de
length
, sinon le comportement de la fonction
est indéfini. Le comportement est indéfini si les chaînes
to
et from
se recouvrent.
Si le paramètre error
est différent de NULL
,
alors *error
est configuré à zéro en cas de succès,
et est différent de zéro en cas d'erreur. Actuellement, les seules
conditions permettant une erreur impliquent des encodages multi-octets
dans la chaîne source. La chaîne en sortie est toujours générée en cas
d'erreur mais on peut s'attendre à ce que le serveur la rejette comme une
chaîne malformée. En cas d'erreur, un message adéquat est stocké dans
l'objet conn
, que error
soit NULL
ou non.
PQescapeStringConn
renvoit le nombre d'octets écrits
dans to
, sans inclure l'octet zéro final.
PQescapeString
#
PQescapeString
est une version ancienne et obsolète de
PQescapeStringConn
.
size_t PQescapeString (char *to, const char *from, size_t length);
La seule différence avec
PQescapeStringConn
tient
dans le fait que PQescapeString
n'a pas de
paramètres conn
et error
.
À cause de cela, elle ne peut ajuster son
comportement en fonction des propriétés de la connexion (comme l'encodage des
cnécssairearactères) et du coup, elle pourrait fournir des résultats
erronés. De plus, elle ne peut pas renvoyer de conditions
d'erreur.
PQescapeString
peut être utilisé en toute sécurité avec
des programmes client utilisant une seule connexion
PostgreSQL à la fois (dans ce cas,
il peut trouver ce qui l'intéresse « en arrière-plan »).
Dans d'autres contextes, c'est un risque en terme de sécurité. Cette
fonction devrait être évitée et remplacée par
PQescapeStringConn
.
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
lorsqu'elles font partie d'un littéral bytea
dans une
instruction SQL. PQescapeByteaConn
échappe les octets en utilisant soit un codage hexadécimal soit un
échappement avec des antislashs. Voir Section 8.4 pour
plus d'informations.
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 final 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 la fonction d'entrée
bytea
. Un octet zéro final est aussi
ajouté. Les guillemets simples qui encadrent 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 ancienne et 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
. De ce fait, PQescapeBytea
ne peut être utilisé en toute sécurité que dans des programmes qui n'utilisent
qu'une seule connexion PostgreSQL à la fois (dans
ce cas, il peut trouver ce dont il a besoin « en arrière-plan »).
Elle pourrait donner des résultats erronés si elle est
utilisé dans des programmes qui utilisent plusieurs connexions de bases de
données (dans ce cas, utilisez 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 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
lorsqu'il n'est plus
nécessaire.
Cette conversion n'est pas l'inverse exacte de PQescapeBytea
car la chaîne n'est pas supposée être "échappée" tel qu'elle est renvoyée
par PQgetvalue
. Cela veut dire, notamment,
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
.