Documentation PostgreSQL 15.15 » Interfaces client » libpq -- Bibliothèque C » Fonctions de statut de connexion

Précédent | Niveau supérieur | Suivant
34.1. Fonctions de contrôle de connexion à la base de données | Sommaire | 34.3. Fonctions d'exécution de commandes

## 34.2. Fonctions de statut de connexion

Ces fonctions sont utilisées pour interroger le statut d'un objet de connexion existant.

### Astuce

Les développeurs d'application libpq devraient être attentif à maintenir l'abstraction `PGconn`. Utilisez les fonctions d'accès décrites ci-dessous pour obtenir le contenu de `PGconn`. Référencer les champs internes de `PGconn` en utilisant `libpq-int.h` n'est pas recommandé parce qu'ils sont sujets à modification dans le futur.

Les fonctions suivantes renvoient les valeurs des paramètres utilisés pour la connexion. Ces valeurs sont fixes pour la durée de vie de la connexion. Si une chaîne de connexion multi-hôtes est utilisée, les valeurs de `PQhost`, `PQport` et `PQpass` peuvent changer si une nouvelle connexion est établie en utilisant le même objet `PGconn`. Les autres valeurs sont figées pour la durée de vie de l'objet `PGconn`.

`PQdb`

  Renvoie le nom de la base de données de la connexion.

      char *PQdb(const PGconn *conn);

`PQuser`

  Renvoie le nom d'utilisateur utilisé pour la connexion.

      char *PQuser(const PGconn *conn);

`PQpass`

  Renvoie le mot de passe utilisé pour la connexion.

      char *PQpass(const PGconn *conn);

  `PQpass` retournera soit le mot de passe spécifié dans les paramètres de connexion, soit, s'il n'y en avait pas, le mot de passe obtenu depuis le fichier de mots de passe. Dans ce dernier cas, si plusieurs hôtes étaient spécifiés dans les paramètres de connexion, il n'est pas possible de se fier au résultat de `PQpass` jusqu'à l'établissement de la connexion. Le statut de la connexion peut être vérifié avec la fonction `PQstatus`.

`PQhost`

  Renvoie le nom d'hôte du serveur utilisé pour la connexion. Cela peut être un nom d'hôte, une adresse IP ou un chemin de répertoire si la connexion est réalisée via un socket Unix. (Le cas du chemin se distingue par le fait que ce sera toujours un chemin absolu commençant par `/`.)

      char *PQhost(const PGconn *conn);

  Si les paramètres de connexion `host` and `hostaddr` sont tous les deux précisés, alors `PQhost` retournera `host`. Si seul `hostaddr` a été spécifié, c'est cela qui est retourné. Si plusieurs hôtes sont spécifiés dans les paramètres de connexion, `PQhost` retourne l'hôte à qui l'on s'est effectivement connecté.

  `PQhost` retourne `NULL` si l'argument `conn` est `NULL`. Sinon, s'il y a une erreur en déterminant l'`host` (peut-être que la connexion n'a pas été complètement établie ou qu'il y a eu une erreur), il retourne une chaîne vide.

  Si plusieurs hôtes ont été spécifiés dans les paramètres de connexion, il n'est pas possible de se baser sur le résultat de `PQhost` avant l'établissement de la connexion. Le statut de la connexion peut être vérifié avec la fonction `PQstatus`.

`PQhostaddr`

  Renvoie l'adresse IP du serveur de la connexion active. Ca peut être l'adresse résultant de la résolution d'un nom d'hôte, ou une adresse IP fournie par le paramètre `hostaddr`.

             char *PQhostaddr(const PGconn *conn);

  `PQhostaddr` renvoie `NULL` si l'argument `conn` est `NULL`. Sinon, si une erreur survient en produisant l'information sur l'hôte (peut-être parce que la connexion n'a pas été complètement établie ou qu'elle a subi une erreur), renvoie une chaîne vide.

`PQport`

  Renvoie le numéro de port utilisé pour la connexion active.

      char *PQport(const PGconn *conn);

  Si de multiples ports étaient spécifiés dans les paramètres de connexion, `PQport` renvoie le port auquel on est effectivement connecté.

  `PQport` retourne `NULL` si l'argument `conn` est `NULL`. Sinon, s'il y a une erreur en déterminant le `port` (peut-être que la connexion n'a pas été complètement établie ou qu'il y a eu une erreur), il retourne une chaîne vide.

  Si plusieurs ports ont été spécifiés dans les paramètres de connexion, il n'est pas possible de se baser sur le résultat de `PQport` avant l'établissement de la connexion. Le statut de la connexion peut être vérifié avec la fonction `PQstatus`.

`PQtty`

  Cette fonction ne fait plus rien, mais elle reste disponible pour des raisons de compatibilité ascendante. La fonction renvoie toujours une chaîne vide ou `NULL` si l'argument `conn` vaut `NULL`.

      char *PQtty(const PGconn *conn);

`PQoptions`

  Renvoie les options en ligne de commande passées lors de la demande de connexion.

      char *PQoptions(const PGconn *conn);

Les fonctions suivantes renvoient des données de statut qui peuvent changer suite à des opérations sur l'objet `PGconn`.

`PQstatus`

  Renvoie l'état de la connexion.

      ConnStatusType PQstatus(const PGconn *conn);

  Le statut peut prendre un certain nombre de valeurs. Néanmoins, deux seulement ne concernent pas les procédures de connexion asynchrone : `CONNECTION_OK` et `CONNECTION_BAD`. Une bonne connexion à la base de données a l'état `CONNECTION_OK`. Une tentative de connexion ayant échoué est signalée par le statut `CONNECTION_BAD`. D'habitude, un état OK le restera jusqu'à `PQfinish` mais un échec dans les communications peut résulter en un statut changeant prématurément en `CONNECTION_BAD`. Dans ce cas, l'application peut essayer de rattraper la situation en appelant `PQreset`.

  Voir l'entrée de `PQconnectStartParams`, `PQconnectStart` et de `PQconnectPoll` à propos des autres codes de statut qui pourraient être renvoyés.

`PQtransactionStatus`

  Renvoie l'état actuel de la transaction du serveur.

      PGTransactionStatusType PQtransactionStatus(const PGconn *conn);

  Le statut peut être `PQTRANS_IDLE` (actuellement inactif), `PQTRANS_ACTIVE` (une commande est en cours), `PQTRANS_INTRANS` (inactif, dans un bloc de transaction valide) ou `PQTRANS_INERROR` (inactif, dans un bloc de transaction échoué). `PQTRANS_UNKNOWN` est rapporté si la connexion est mauvaise. `PQTRANS_ACTIVE` n'est rapporté que si une requête a été envoyée au serveur et n'est pas encore terminée.

`PQparameterStatus`

  Recherche la valeur en cours d'un paramètre du serveur.

      const char *PQparameterStatus(const PGconn *conn, const char *paramName);

  Certaines valeurs de paramètres sont rapportées par le serveur automatiquement ou lorsque leur valeurs changent. `PQparameterStatus` peut être utilisé pour interroger ces paramètres. Il renvoie la valeur en cours d'un paramètre s'il est connu et `NULL` si le paramètre est inconnu.

  Les paramètres renvoyées par la version actuelle incluent `server_version`, `server_encoding`, `client_encoding`, `application_name`, `default_transaction_read_only`, `in_hot_standby`, `is_superuser`, `session_authorization`, `datestyle`, `IntervalStyle`, `TimeZone`, `integer_datetimes` et `standard_conforming_strings`. (`server_encoding`, `TimeZone` et `integer_datetimes` n'étaient pas renvoyés dans les versions antérieures à la 8.0 ; `standard_conforming_strings` n'était pas renvoyé dans les versions antérieures à la 8.1 ; `IntervalStyle` n'était pas renvoyé dans les versions antérieures à la 8.4 ; `application_name` n'était pas renvoyé dans les versions antérieures à la 9.0 ; `default_transaction_read_only` et `in_hot_standby` n'étaient pas renvoyés dans les versions antérieures à la 14.). Notez que `server_version`, `server_encoding` et `integer_datetimes` ne peuvent pas changer après le lancement du serveur.

  Si aucune valeur n'est indiquée pour `standard_conforming_strings`, les applications peuvent considérer qu'elle vaut `off`, c'est-à-dire que les antislashs sont traités comme des échappements dans les chaînes littérales. De plus, la présence de ce paramètre peut être pris comme une indication que la syntaxe d'échappement de chaîne (`E'...'`) est acceptée.

  Bien que le pointeur renvoyé est déclaré `const`, il pointe en fait vers un stockage mutable associé à la structure `PGconn`. Il est déconseillé de supposer que le pointeur restera valide pour toutes les requêtes.

`PQprotocolVersion`

  Interroge le protocole interface/moteur lors de son utilisation.

      int PQprotocolVersion(const PGconn *conn);

  Les applications peuvent utiliser ceci pour déterminer si certaines fonctionnalités sont supportées. Actuellement, les seules valeurs possible sont 3 (protocole 3.0) ou zéro (mauvaise connexion). La version du protocole ne changera pas après la fin du lancement de la connexion mais il pourrait théoriquement changer lors d'une réinitialisation de la connexion. Le protocole 3.0 est supporté par les versions 7.4 et suivantes de PostgreSQL.

`PQserverVersion`

  Renvoie un entier représentant la version du moteur.

      int PQserverVersion(const PGconn *conn);

  Les applications peuvent utiliser cette fonction pour déterminer la version du serveur de bases de données où ils sont connectés Le résultat est obtenu en multipliant le numéro de version majeure de la bibliothèque par 10000 et en ajoutant le numéro de version mineure. Par exemple, la version 10.1 renverra 100001, et la version 11.0 renverra 110000. Zéro est renvoyé si la connexion est mauvaise.

  Avant la version majeure 10, PostgreSQL utilisait des numéros de version en trois parties, pour lesquelles les deux premières parties représentaient la version majeure. Pour ces versions, `PQlibVersion` utilise deux chiffres pour chaque partie. Par exemple, la version 9.1.5 renverra 90105, et la version 9.2.0 renverra 90200.

  De ce fait, pour déterminer la compatibilité de certaines fonctionnalités, les applications devrait diviser le résultat de `PQserverVersion` par 100, et non pas par 10000, pour déterminer le numéro de version majeure logique. Dans toutes les versions, seuls les deux derniers chiffres diffèrent entre des versions mineures (versions correctives).

`PQerrorMessage`

  Renvoie le dernier message d'erreur généré par une opération sur la connexion.

      char *PQerrorMessage(const PGconn* conn);

  Pratiquement toutes les fonctions libpq initialiseront un message pour `PQerrorMessage` en cas d'échec. Notez que, par convention dans libpq, un résultat non vide de `PQerrorMessage` peut courir sur plusieurs lignes et finira par un retour chariot. L'appelant ne devrait pas libérer directement le résultat. Il sera libéré quand le pointeur `PGconn` associé sera passé à `PQfinish`. La chaîne résultante n'est pas supposée rester la même pendant les opérations sur la structure `PGconn`.

`PQsocket`

  Obtient le descripteur de fichier du socket de la connexion au serveur. Un descripteur valide sera plus grand ou égal à 0 ; un résultat de -1 indique qu'aucune connexion au serveur n'est actuellement ouverte (ceci ne changera pas lors du fonctionnement habituel, mais pourrait changer lors de la mise en place de la connexion ou lors d'une réinitialisation).

      int PQsocket(const PGconn *conn);

`PQbackendPID`

  Renvoie l'identifiant du processus (PID) du serveur gérant cette connexion.

      int PQbackendPID(const PGconn *conn);

  Le PID du processus backend est utile pour des raisons de débogage et pour la comparaison avec les messages `NOTIFY` (qui incluent le PID du processus serveur lançant la notification). Notez que le PID appartient à un processus exécuté sur l'hôte du serveur de bases de données et non pas sur l'hôte local !

`PQconnectionNeedsPassword`

  Renvoie true (1) si la méthode d'authentification de la connexion nécessite un mot de passe, mais qu'aucun n'est disponible. Renvoie false (0) sinon.

              int PQconnectionNeedsPassword(const PGconn *conn);

  Cette fonction peut être utilisée après un échec de connexion pour décider s'il faut demander un mot de passe à l'utilisateur.

`PQconnectionUsedPassword`

  Renvoie true (1) si la méthode d'authentification de la connexion a utilisé un mot de passe. Renvoie false (0) sinon.

              int PQconnectionUsedPassword(const PGconn *conn);

  Cette fonction peut être utilisée après une connexion, réussie ou en échec, pour détecter si le serveur demande un mot de passe.

Les fonctions ci-dessous renvoient des informations relatives à SSL. Cette information ne change généralement pas après qu'une connexion soit établie.

`PQsslInUse`

  Renvoie true (1) si la connexion utilise SSL, false (0) dans le cas contraire.

      int PQsslInUse(const PGconn *conn);

`PQsslAttribute`

  Renvoie des informations relatives à SSL à propos de la connexion.

      const char *PQsslAttribute(const PGconn *conn, const char *attribute_name);

  La liste des attributs disponibles varie en fonction de la bibliothèque SSL utilisée, et du type de la connexion. Renvoie NULL si la connexion n'utilise pas SSL ou si le nom de l'attribut spécifié n'est pas défini pour la bibliothèque utilisée.

  Les attributs suivants sont communément disponibles :

  `library`

    Nom de l'implémentation SSL utilisée. (À ce jour seul `"OpenSSL"` est implémenté)

  `protocol`

    Version de SSL/TLS utilisée. Les valeurs courantes sont `"TLSv1"`, `"TLSv1.1"` and `"TLSv1.2"`, mais une implémentation peut renvoyer d'autres chaînes si d'autres protocoles sont utilisés.

  `key_bits`

    Nombre de bits de la clef utilisée par l'algorithme de chiffrement.

  `cipher`

    Le nom raccourci de la suite cryptographique utilisée, par exemple `"DHE-RSA-DES-CBC3-SHA"`. Les noms sont spécifiques à chaque implémentation.

  `compression`

    Renvoie "on" si la compression SSL est utilisée, sinon renvoie "off".

  Comme cas particulier, l'attribut `library` peut être requêté sans connexion en passant NULL à l'argument `conn`. Le résultat sera le nom de la bibliothèque SSL par défaut ou NULL si libpq a été compilé sans le support SSL. (Avant PostgreSQL version 15, passer NULL pour l'argument `conn` résultait toujours en un NULL. Les programmes clients qui ont besoin de différencier entrer les implémentations nouvelle et ancienne dans ce cas peuvent vérifier la macro `LIBPQ_HAS_SSL_LIBRARY_DETECTION`.)

`PQsslAttributeNames`

  Renvoie un tableau des noms d'attribut SSL disponibles. Le tableau est terminé par un pointeur NULL.

      const char * const * PQsslAttributeNames(const PGconn *conn);

`PQsslStruct`

  Renvoie un pointeur sur un objet SSL qui est dépendant de l'implémentation et qui décrit la connexion. Renvoie NULL si la connexion n'est pas chiffrée ou si le type demandé d'un objet n'est pas disponible à partir de l'implémentation SSL de la connexion.

      void *PQsslStruct(const PGconn *conn, const char *struct_name);

  Là où les structures disponibles dépendent de l'implémentation SSL utilisée. Pour OpenSSL, il y a une structure, disponible sous le nom `OpenSSL`, qui renvoie un pointeur sur la structure `SSL` d'OpenSSL. Un exemple de code utilisant cette fonction pourrait être :

       #include <libpq-fe.h>
       #include <openssl/ssl.h>

       ...

           SSL *ssl;

           dbconn = PQconnectdb(...);
           ...

           ssl = PQsslStruct(dbconn, "OpenSSL");
           if (ssl)
           {
               /* utilisez les fonctions OpenSSL pour accéder à ssl */
           }

  Cette structure peut être utilisée pour vérifier les niveaux de chiffrement, les certificats du serveur, etc. Référez-vous à la documentation d'OpenSSL pour des informations sur cette structure.

`PQgetssl`

  Renvoie la structure SSL utilisée dans la connexion, ou NULL si SSL n'est pas utilisé.

      void *PQgetssl(const PGconn *conn);

  Cette fonction est équivalente à `PQsslStruct(conn, "OpenSSL")`. Elle ne devrait pas être utilisée dans les nouvelles applications, car la structure renvoyée est spécifique à OpenSSL et ne sera pas disponible si une autre implémentation SSL est utilisée. Pour vérifier si une connexion utilise SSL, appelez plutôt `PQsslInUse`, et, pour plus de détails à propos de la connexion, utilisez `PQsslAttribute`.