53.7. Formats de message

» » »

Précédent	Niveau supérieur	Suivant
53.6. Protocole de réplication en continu	Sommaire	53.8. Champs des messages d'erreur et d'avertissement

53.7. Formats de message

Cette section décrit le format détaillé de chaque message. Chaque message est marqué pour indiquer s'il peut être envoyé par un client (F pour frontend), un serveur (B pour backend) ou les deux (F & B). Bien que chaque message commence par son nombre d'octets, le format du message est défini de telle sorte que la fin du message puisse être trouvée sans ce nombre. Cela contribue à la vérification de la validité. Le message CopyData est une exception, car il constitue une partie du flux de données ; le contenu d'un message CopyData individuel n'est, en soi, pas interprétable.

AuthenticationOk (B)

Byte1('R'): Marqueur de demande d'authentification.
Int32(8): Taille du message en octets, y compris la taille elle-même.
Int32(0): L'authentification a réussi.

AuthenticationKerberosV5 (B)

Byte1('R'): Marqueur de demande d'authentification.
Int32(8): Taille du message en octets, y compris la taille elle-même.
Int32(2): Une authentification Kerberos V5 est requise.

AuthenticationCleartextPassword (B)

Byte1('R'): Marqueur de demande d'authentification.
Int32(8): Taille du message en octets, y compris la taille elle-même.
Int32(3): Un mot de passe en clair est requis.

AuthenticationMD5Password (B)

Byte1('R'): Marqueur de demande d'authentification.
Int32(12): Taille du message en octets, y compris la taille elle-même.
Int32(5): Spécifie qu'un mot de passe utilisant un hachage cryptographique par MD5 est requis.
Byte4: Composante de salage (salt) à utiliser lors du hachage du mot de passe.

AuthenticationSCMCredential (B)

Byte1('R'): Marqueur de demande d'authentification.
Int32(8): Taille du message en octets, y compris la taille elle-même.
Int32(6): Un message d'accréditation SCM est requis.

AuthenticationGSS (B)

Byte1('R'): Identifie le message en tant que requête d'authentification.
Int32(8): Longueur du contenu du message en octets, lui-même inclus.
Int32(7): Spécifie qu'une authentification GSSAPI est requise.

AuthenticationSSPI (B)

Byte1('R'): Identifie le message en tant que requête d'authentification.
Int32(8): Longueur du message en octet, incluant la longueur.
Int32(9): Spécifie que l'authentification SSPI est requise.

AuthenticationGSSContinue (B)

Byte1('R'): Identifie le message comme une requête d'authentification.
Int32: Longueur du message en octet, incluant la longueur.
Int32(8): Spécifie que ce message contient des données GSSAPI ou SSPI.
Byten: Données d'authentification GSSAPI ou SSPI.

AuthenticationSASL (B)

Byte1('R'): Identifie le message comme une demande d'authentification.
Int32: Taille du message en octets, y compris la taille elle-même.
Int32(10): Précise qu'une authentification SASL est requise.

Le corps du message est une liste de mécanismes d'authentification SASL dans l'ordre de préférence du serveur. Un octet zéro est requis comme fin de chaîne après le nom du dernier mécanisme d'authentification. Pour chaque mécanisme, il existe ce qui suit :

String: Nom du mécanisme d'authentification SASL.

AuthenticationSASLContinue (B)

Byte1('R'): Identifie le message comme une demande d'authentification.
Int32: Taille du message en octets, y compris la taille elle-même.
Int32(11): Précise que ce message contient un challenge SASL.
Byten: Données SASL, spécifiques au mécanisme SASL utilisé.

AuthenticationSASLFinal (B)

Byte1('R'): Identifie le message comme une demande d'authentification.
Int32: Taille du message en octets, y compris la taille elle-même.
Int32(12): Indique que l'authentification SASL est terminée.
Byten: Données supplémentaires pour SASL, spécifique au mécanisme SASL utilisé.

BackendKeyData (B)

Byte1('K'): Identifie le message comme une donnée clé d'annulation. L'interface (frontend) doit sauvegarder ces valeurs si elle souhaite être capable d'envoyer des messages CancelRequest plus tard.
Int32(12): Longueur du contenu du message en octet incluent lui-même.
Int32: L'identifiant du processus serveur.
Int32: La clé secrète de ce processus serveur.

Bind (F)

Byte1('B'): Identifie le message comme une commande Bind.
Int32: Longueur du contenu du message en octets incluant lui-même.
String: Le nom du portail destination (une chaîne vide sélectionne le portail non nommé).
String: Le nom de l'instruction préparée source (une chaîne vide sélectionne l'instruction préparée sans nom).
Int16: Le nombre de codes de format de paramètre qui suivent (dénoté C ci-dessous). Il peut valoir zéro pour indiquer qu'il n'y a pas de paramètres ou que tous les paramètres utilisent le format par défaut (texte) ; il peut valoir un, auquel cas le code de format spécifié est appliqué à tous les paramètres ; ou il peut valoir le nombre réel de paramètres.
Int16[C]: Les codes de format de la commande. Chaque code doit être exactement zéro (texte) ou un (binaire).
Int16: Le nombre de valeurs de paramètre qui suivent (potentiellement zéro). Ceci doit correspondre au nombre de paramètres nécessaires à la requête.

Puis, le couple de champs suivant apparaît pour chaque paramètre : paramètre :

Int32: Taille de la valeur du paramètre, en octets (ce nombre n'inclut pas la longueur elle-même). Peut valoir zéro. Traité comme un cas spécial, -1 indique une valeur de paramètre NULL. Aucun octet de valeur ne suit le cas NULL.
Byten: Valeur du paramètre, dans le format indiqué par le code de format associé. n est la longueur ci-dessus.

Après le dernier paramètre, les champs suivants apparaissent :

Int16: Nombre de codes de format des colonnes de résultat qui suivent (noté r ci-dessous). Peut valoir zéro pour indiquer qu'il n'y a pas de colonnes de résultat ou que les colonnes de résultat utilisent le format par défaut (texte) ; ou une, auquel cas le code de format spécifié est appliqué à toutes les colonnes de résultat (s'il y en a) ; il peut aussi être égal au nombre de colonnes de résultat de la requête.
Int16[r]: Codes de format des colonnes de résultat. Tous doivent valoir zéro (texte) ou un (binaire).

BindComplete (B)

Byte1('2'): Indicateur de Bind complet.
Int32(4): Taille du message en octets, y compris la taille elle-même.

CancelRequest (F)

Int32(16): Taille du message en octets, y compris la taille elle-même.
Int32(80877102): Code d'annulation de la requête. La valeur est choisie pour contenir 1234 dans les 16 bits les plus significatifs et 5678 dans les 16 bits les moins significatifs (pour éviter toute confusion, ce code ne doit pas être le même qu'un numéro de version de protocole).
Int32: ID du processus du serveur cible.
Int32: Clé secrète du serveur cible.

Close (F)

Byte1('C'): Marqueur de commande Close.
Int32: Taille du message en octets, y compris la taille elle-même.
Byte1: 's' pour fermer une instruction préparée ; ou 'p' pour fermer un portail.
String: Nom de l'instruction préparée ou du portail à fermer (une chaîne vide sélectionne l'instruction préparée ou le portail non-nommé(e)).

CloseComplete (B)

Byte1('3'): Indicateur de complétude de Close.
Int32(4): Taille du message en octets, y compris la taille elle-même.

CommandComplete (B)

Byte1('C')

Marqueur de réponse de complétude de commande.

Int32

Taille du message en octets, y compris la taille elle-même.

String

Balise de la commande. Mot simple identifiant la commande SQL terminée.

Pour une commande insert, la balise est insert oid lignes où lignes est le nombre de lignes insérées. oid est l'id de l'objet de la ligne insérée si lignes vaut 1 et que la table cible a des OID ; sinon oid vaut 0.

Pour une commande delete, la balise est delete lignes où lignes est le nombre de lignes supprimées.

Pour une commande update, la balise est update lignes où lignes est le nombre de lignes mises à jour.

Pour les commandes SELECT ou CREATE TABLE AS, la balise est SELECT lignes où lignes est le nombre de lignes récupérées.

Pour une commande move, la balise est move lignes où lignes est le nombre de lignes de déplacement du curseur.

Pour une commande fetch, la balise est fetch lignes où lignes est le nombre de lignes récupérées à partir du curseur.

CopyData (F & B)

Byte1('d'): Marqueur de données de COPY.
Int32: Taille du message en octets, y compris la taille elle-même.
Byten: Données formant une partie d'un flux de données copy. Les messages envoyés depuis le serveur correspondront toujours à des lignes uniques de données, mais les messages envoyés par les clients peuvent diviser le flux de données de façon arbitraire.

CopyDone (F & B)

Byte1('c'): Indicateur de fin de COPY.
Int32(4): Taille du message en octets, y compris la taille elle-même.

CopyFail (F)

Byte1('f'): Indicateur d'échec de COPY.
Int32: Taille du message en octets, y compris la taille elle-même.
String: Message d'erreur rapportant la cause d'un échec.

CopyInResponse (B)

Byte1('G'): Marqueur de réponse de Start Copy In. Le client doit alors envoyer des données de copie (s'il n'est pas à cela, il enverra un message CopyFail).
Int32: Taille du message en octets, y compris la taille elle-même.
Int8: 0 indique que le format de copie complet est textuel (lignes séparées par des retours chariot, colonnes séparées par des caractères de séparation, etc). 1 indique que le format de copie complet est binaire (similaire au format DataRow). Voir COPY pour plus d'informations.
Int16: Nombre de colonnes dans les données à copier (noté n ci-dessous).
Int16[n]: Codes de format à utiliser pour chaque colonne. Chacun doit valoir zéro (texte) ou un (binaire). Tous doivent valoir zéro si le format de copie complet est de type texte.

CopyOutResponse (B)

Byte1('H'): Marqueur de réponse Start Copy Out. Ce message sera suivi de données copy-out.
Int32: Taille du message en octets, y compris la taille elle-même.
Int8: 0 indique que le format de copie complet est textuel (lignes séparées par des retours chariot, colonnes séparées par des caractères séparateurs, etc). 1 indique que le format de copie complet est binaire (similaire au format DataRow). Voir COPY pour plus d'informations.
Int16: Nombre de colonnes de données à copier (noté n ci-dessous).
Int16[n]: Codes de format à utiliser pour chaque colonne. Chaque code doit valoir zéro (texte) ou un (binaire). Tous doivent valoir zéro si le format de copie complet est de type texte.

NegotiateProtocolVersion (B)

Byte1('v'): Identifie le message comme un message de négociation de la version du protocole.
Int32: Longueur du contenu du message en octets, incluant la longueur elle-même.
Int32: Plus récente version mineure supportée par le serveur pour la version majeure du protocole demandée par le client.
Int32: Nombre d'options du protocole non reconnues par le serveur.

Puis, pour chaque option du protocole non reconnue par le serveur :

String: Nom de l'option.

CopyBothResponse (B)

Byte1('W'): Identifie le message comme une réponse Start Copy Both. Ce message est seulement utilisé pour la réplication en flux.
Int32: Longueur du contenu du message en octets, incluant lui-même.
Int8: 0 indique que le format COPY global est textuel (lignes séparées par des retours à la ligne, colonnes séparées par des caractères séparateurs, etc). 1 indique que le format de copie global est binaire (similaire au format DataRow). Voir COPY pour plus d'informations.
Int16: Le nombre de colonnes dans les données à copier (dénoté N ci-dessous).
Int16[N]: Les codes de format utilisés pour chaque colonne. Chacune doit actuellement valoir 0 (texte) ou 1 (binaire). Tous doivent valoir 0 si le format de copy global est texte.

DataRow (B)

Byte1('D'): Marqueur de ligne de données.
Int32: Taille du message en octets, y compris la taille elle-même.
Int16: Nombre de valeurs de colonnes qui suivent (peut valoir zéro).

Apparaît ensuite le couple de champs suivant, pour chaque colonne :

Int32: Longueur de la valeur de la colonne, en octets (ce nombre n'inclut pas la longueur elle-même). Elle peut valoir zéro. Traité comme un cas spécial, -1 indique une valeur NULL de colonne. Aucun octet de valeur ne suit le cas NULL.
Byten: Valeur de la colonne dans le format indiqué par le code de format associé. n est la longueur ci-dessus.

Describe (F)

Byte1('D'): Marqueur de commande Describe.
Int32: Taille du message en octets, y compris la taille elle-même.
Byte1: 's' pour décrire une instruction préparée ; ou 'p' pour décrire un portail.
String: Nom de l'instruction préparée ou du portail à décrire (une chaîne vide sélectionne l'instruction préparée ou le portail non-nommé(e)).

EmptyQueryResponse (B)

Byte1('I'): Marqueur de réponse à une chaîne de requête vide (c'est un substitut de CommandComplete).
Int32(4): Taille du message en octets, y compris la taille elle-même.

ErrorResponse (B)

Byte1('E'): Marqueur d'erreur.
Int32: Taille du message en octets, y compris la taille elle-même.

Le corps du message est constitué d'un ou plusieurs champs identifié(s), suivi(s) d'un octet nul comme délimiteur de fin. L'ordre des champs n'est pas fixé. Pour chaque champ, on trouve les informations suivantes :

Byte1: Code identifiant le type de champ ; s'il vaut zéro, c'est la fin du message et aucune chaîne ne suit. Les types de champs définis sont listés dans Section 53.8. De nouveaux types de champs pourraient être ajoutés dans le futur, les clients doivent donc ignorer silencieusement les types non reconnus.
String: Valeur du champ.

Execute (F)

Byte1('E'): Marqueur de commande Execute.
Int32: Taille du message en octets, y compris la taille elle-même.
String: Nom du portail à exécuter (une chaîne vide sélectionne le portail non-nommé).
Int32: Nombre maximum de lignes à retourner si le portail contient une requête retournant des lignes (ignoré sinon). Zéro signifie : « aucune limite ».

Flush (F)

Byte1('H'): Marqueur de commande Flush.
Int32(4): Taille du message en octets, y compris la taille elle-même.

FunctionCall (F)

Byte1('F'): Marqueur d'appel de fonction.
Int32: Taille du message en octets, y compris la taille elle-même.
Int32: Spécifie l'ID de l'objet représentant la fonction à appeler.
Int16: Nombre de codes de format de l'argument qui suivent (noté c ci-dessous). Cela peut être zéro pour indiquer qu'il n'y a pas d'arguments ou que tous les arguments utilisent le format par défaut (texte) ; un, auquel cas le code de format est appliqué à tous les arguments ; il peut aussi être égal au nombre réel d'arguments.
Int16[c]: Les codes de format d'argument. Chacun doit valoir zéro (texte) ou un (binaire).
Int16: Nombre d'arguments fournis à la fonction.

Apparaît ensuite, pour chaque argument, le couple de champs suivant :

Int32: Longueur de la valeur de l'argument, en octets (ce nombre n'inclut pas la longueur elle-même). Peut valoir zéro. Traité comme un cas spécial, -1 indique une valeur NULL de l'argument. Aucun octet de valeur ne suit le cas NULL.
Byten: Valeur de l'argument dans le format indiqué par le code de format associé. n est la longueur ci-dessus.

Après le dernier argument, le champ suivant apparaît :

Int16: Code du format du résultat de la fonction. Doit valoir zéro (texte) ou un (binaire).

FunctionCallResponse (B)

Byte1('V'): Marqueur de résultat d'un appel de fonction.
Int32: Taille du message en octets, y compris la taille elle-même.
Int32: Longueur de la valeur du résultat de la fonction, en octets (ce nombre n'inclut pas la longueur elle-même). Peut valoir zéro. Traité comme un cas spécial, -1 indique un résultat de fonction NULL. Aucun octet de valeur ne suit le cas NULL.
Byten: Valeur du résultat de la fonction, dans le format indiqué par le code de format associé. n est la longueur ci-dessus.

GSSResponse (F)

Byte1('p'): Identifie le message comme une réponse GSSAPI ou SSPI. Notez que ceci peut aussi être utilisé comme message de réponse SASL et password. Le type de message exact se déduit du contexte.
Int32: Longueur du contenu du message en octets, incluant lui-même.
Byten: Données spécifiques du message GSSAPI/SSPI.

NoData (B)

Byte1('n'): Indicateur d'absence de données.
Int32(4): Taille du message en octets, y compris la taille elle-même.

NoticeResponse (B)

Byte1('N'): Marqueur d'avertissement.
Int32: Taille du message en octets, y compris la taille elle-même.

Le corps du message est constitué d'un ou plusieurs champs identifié(s), suivi(s) d'un octet zéro comme délimiteur de fin. L'ordre des champs n'est pas fixé. Pour chaque champ, on trouve les informations suivantes :

Byte1: Code identifiant le type de champ ; s'il vaut zéro, c'est la fin du message et aucune chaîne ne suit. Les types de champs déjà définis sont listés dans Section 53.8. De nouveaux types de champs pourraient être ajoutés dans le futur, les clients doivent donc ignorer silencieusement les champs de type non reconnu.
String: Valeur du champ.

NotificationResponse (B)

Byte1('A'): Marqueur de réponse de notification.
Int32: Taille du message en octets, y compris la taille elle-même.
Int32: ID du processus serveur ayant procédé à la notification.
String: Nom du canal à l'origine de la notification.
String: La chaîne « embarquée » passée lors de la notification

ParameterDescription (B)

Byte1('t'): Marqueur de description de paramètre.
Int32: Taille du message en octets, y compris la taille elle-même.
Int16: Nombre de paramètres utilisé par l'instruction (peut valoir zéro).

Pour chaque paramètre, on trouve ensuite :

Int32: ID de l'objet du type de données du paramètre.

ParameterStatus (B)

Byte1('S'): Marqueur de rapport d'état de paramètre d'exécution.
Int32: Taille du message en octets, y compris la taille elle-même.
String: Nom du paramètre d'exécution dont le rapport est en cours.
String: Valeur actuelle du paramètre.

Parse (F)

Byte1('P'): Marqueur de commande Parse.
Int32: Taille du message en octets, y compris la taille elle-même.
String: Nom de l'instruction préparée de destination (une chaîne vide sélectionne l'instruction préparée non-nommée).
String: Chaîne de requête à analyser.
Int16: Nombre de types de données de paramètre spécifiés (peut valoir zéro). Ce n'est pas une indication du nombre de paramètres pouvant apparaître dans la chaîne de requête, mais simplement le nombre de paramètres pour lesquels le client veut préspécifier les types.

Pour chaque paramètre, on trouve ensuite :

Int32: ID de l'objet du type de données du paramètre. La valeur zéro équivaut à ne pas spécifier le type.

ParseComplete (B)

Byte1('1'): Indicateur de fin de Parse.
Int32(4): Taille du message en octets, y compris la taille elle-même.

PasswordMessage (F)

Byte1('p'): Identifie le message comme une réponse à un mot de passe. Notez que c'est aussi utilisé par les messages de réponse GSSAPI, SSPI et SASL. Le type exact du message se déduit du contexte.
Int32: Taille du message en octets, y compris la taille elle-même.
String: Mot de passe (chiffré à la demande).

PortalSuspended (B)

Byte1('s'): Indicateur de suspension du portail. Apparaît seulement si la limite du nombre de lignes d'un message Execute a été atteinte.
Int32(4): Taille du message en octets, y compris la taille elle-même.

Query (F)

Byte1('Q'): Marqueur de requête simple.
Int32: Taille du message en octets, y compris la taille elle-même.
String: La chaîne de requête elle-même.

ReadyForQuery (B)

Byte1('Z'): Identifie le type du message. ReadyForQuery est envoyé à chaque fois que le serveur est prêt pour un nouveau cycle de requêtes.
Int32(5): Taille du message en octets, y compris la taille elle-même.
Byte1: Indicateur de l'état transactionnel du serveur. Les valeurs possibles sont 'i' s'il est en pause (en dehors d'un bloc de transaction) ; 't' s'il est dans un bloc de transaction ; ou 'e' s'il est dans un bloc de transaction échouée (les requêtes seront rejetées jusqu'à la fin du bloc).

RowDescription (B)

Byte1('T'): Marqueur de description de ligne.
Int32: Taille du message en octets, y compris la taille elle-même.
Int16: Nombre de champs dans une ligne (peut valoir zéro).

On trouve, ensuite, pour chaque champ :

String: Nom du champ.
Int32: Si le champ peut être identifié comme colonne d'une table spécifique, l'ID de l'objet de la table ; sinon zéro.
Int16: Si le champ peut être identifié comme colonne d'une table spécifique, le numéro d'attribut de la colonne ; sinon zéro.
Int32: ID de l'objet du type de données du champ.
Int16: Taille du type de données (voir pg_type.typlen). Les valeurs négatives indiquent des types de largeur variable.
Int32: Modificateur de type (voir pg_attribute.atttypmod). La signification du modificateur est spécifique au type.
Int16: Code de format utilisé pour le champ. Zéro (texte) ou un (binaire), à l'heure actuelle. Dans un RowDescription retourné par la variante de l'instruction de Describe, le code du format n'est pas encore connu et vaudra toujours zéro.

SASLInitialResponse (F)

Byte1('p'): Identifie le message comme une réponse SASL initiale. Notez que c'est aussi utilisé pour les messages de réponses pour GSSAPI, SSPI et password. Le type exact du message se déduit du contexte.
Int32: Longueur du contenu du message en octets incluant lui-même.
String: Nom du mécanisme d'authentification SASL que le client a sélectionné.
Int32: Longueur spécifique au mécanisme SASL pour le "Initial Client Response" qui suit, ou -1 s'il n'y a pas de réponse initiale.
Byten: "Initial Response" spécifique au mécanisme SASL.

SASLResponse (F)

Byte1('p'): Identifie le message comme une réponse SASL. Notez que ceci peut aussi être utilisé pour les messages de réponses pour GSSAPI, SSPI et password. Le type exact de message peut être déduit du contexte.
Int32: Longueur du contenu du message en octets, incluant sa propre longueur.
Byten: Données du message, spécifiques au mécanisme SASL.

SSLRequest (F)

Int32(8): Longueur du contenu du message en octets, incluant sa propre longueur.
Int32(80877103): Le code de demande SSL. La valeur est choisie pour contenir 1234 dans les 16 bits les plus significatifs, et 5679 dans les 16 bits les moins significatifs. (Pour éviter la confusion, ce code ne doit pas être le même que tout numéro de version du procotole.)

StartupMessage (F)

Int32: Longueur du contenu du message en octets, incluant sa propre longueur.
Int32(196608): Le numéro de version du protocole. Les 16 bits les plus significatifs sont le numéro de version du protocole (3 pour le protocole décrit ici). Les 16 bits les moins significatifs sont le numéro de version mineure (0 pour le protocole décrit ici).

Le numéro de version du protocole est suivi par une ou plusieurs paires de nom de paramètre / chaîne de valeur. Un octet zéro est requis comme terminateur après la dernière paire nom/valeur. Les paramètres peuvent apparaître dans n'importe quel ordre. user est requis. Chaque paramètre est spécifié sous cette forme :

String

Le nom du paramètre. Les noms actuellement reconnus sont :

user: Le nom de l'utilisateur pour la connexion. Requis, sans valeur par défaut.
database: Base de données à laquelle se connecter. Par défaut le nom de l'utilisateur.
options: Arguments en ligne de commande pour le serveur (rendu obsolète par l'utilisation de paramètres individuels d'exécution). Les espaces dans cette chaîne sont considérés séparer les arguments, sauf s'ils sont échappés avec un antislash (\). Écrire \\ pour représenter un antislash littéral.
replication: Utiliser pour connecter en mode de réplication en flux, où un petit ensemble de commandes de réplication peuvent être exécutées à la place de requêtes SQL. La valeur peut être true, false ou database, mais la valeur par défaut est false. Voir Section 53.6 pour les détails.

En plus de ce qui est indiqué ci-dessus, les autres paramètres peuvent être listés. Les noms de paramètres commençant par _pq_. sont réservés à être utilisés comme des extensions du protocole, alors que les autres sont traités comme des paramètres à l'exécution à configurer au démarrage de la session. De tels paramètres seront appliqués au lancement du processus (après avoir analysé les arguments de la ligne de commande) et agiront comme les valeurs par défaut de la session.

String

Valeur du paramètre.

Sync (F)

Byte1('S'): Marqueur de commande Sync.
Int32(4): Taille du message en octets, y compris la taille elle-même.

Terminate (F)

Byte1('X'): Marqueur de fin.
Int32(4): Taille du message en octets, y compris la taille elle-même.