Cette section décrit le format détaillé de chaque message. Tous sont marqués pour indiquer qu'ils peuvent être envoyés par un client (F, pour frontend en anglais), par un backend (B) ou les deux (F & B). Notez que, bien que chaque message inclut un décompte d'octets au début, le format de message est défini pour que la fin du message puisse être trouvée sans faire référence au nombre d'octets. Ceci aide à vérifier la validité du message. (Le message CopyData est une exception car il fait partie d'un flux de données ; le contenu de tout message CopyData individuel ne peut pas être interprété indépendamment.)
Identifie le message comme une demande d'authentification.
Longueur du contenu du message en octets, longueur inclue.
Indique que l'authentification est réussie.
Identifie le message comme une demande d'authentification.
Longueur du contenu du message en octets, longueur inclue.
Indique que l'authentification Kerberos V5 est requise.
Identifie le message comme une demande d'authentification.
Longueur du contenu du message en octets, longueur inclue.
Indique que l'authentification par mot de passe en clair en requise.
Identifie le message comme une demande d'authentification.
Longueur du contenu du message en octets, longueur inclue.
Indique que le mot de passe chiffré avec MD5 est requis.
Le sel à utiliser lors du chiffrement du mot de passe.
Identifie le message comme une demande d'authentification.
Longueur du contenu du message en octets, longueur inclue.
Indique qu'un message d'identification SCM est requis.
Identifie le message comme une demande d'authentification.
Longueur du contenu du message en octets, longueur inclue.
Indique qu'une authentification GSSAPI est requise.
Identifie le message comme une demande d'authentification.
Longueur du contenu du message en octets, longueur inclue.
Indique que ce message contient des données GSSAPI ou SSPI.
n
Données d'authentification GSSAPI ou SSPI.
Identifie le message comme une demande d'authentification.
Longueur du contenu du message en octets, longueur inclue.
Indique que l'authentification SSPI est requise.
Identifie le message comme une demande d'authentification.
Longueur du contenu du message en octets, longueur inclue.
Indique que l'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 en fin après le nom du dernier mécanisme d'authentification. Pour chaque mécanisme, il y a ce qui suit :
Nom d'un mécanisme d'authentification SASL.
Identifie le message comme une demande d'authentification.
Longueur du contenu du message en octets, longueur inclue.
Indique que ce message contient un challenge SASL.
n
Données SASL, spécifiques au mécanisme SASL utilisé.
Identifie le message comme une demande d'authentification.
Longueur du contenu du message en octets, longueur inclue.
Indique que l'authentification SASL s'est terminée.
n
Données supplémentaires SASL, spécifique au mécanisme SASL utilisé.
Identifie le message comme une donnée clé d'annulation. Le client doit conserver ces valeurs s'il souhaite être capable d'exécuter ultérieurement des messages CancelRequest.
Longueur du contenu du message en octets, longueur inclue.
Identifiant du processus de ce backend.
Clé secrète de ce backend.
Identifie le message comme une commande Bind.
Longueur du contenu du message en octets, longueur inclue.
Le nom du portail de destination (une chaîne vide sélectionne le portail non nommé).
Le nom de la requête préparée source (une chaîne vide sélectionne la requête préparée non nommée).
Le nombre de codes format des paramètres
(dénoté C
ci-dessous).
Il peut valoir zéro pour indiquer qu'il n'y a pas de paramètres ou
que les paramètres peuvent tous utiliser le format par défaut
(text) ; ou un, auquel cas le code format spécifié est appliqué
à tous les paramètres ; ou il peut être égal au nombre réel
de paramètres.
C
]Les codes format des paramètres. Il n'y a que deux valeurs possibles : zéro pour texte, un pour binaire.
Le nombre de valeurs de paramètres (potentiellement zéro). Ce nombre doit correspondre au nombre de paramètres nécessaires pour la requête.
Ensuite, la paire suivante de champs apparaît pour chaque paramètre :
La longueur de la valeur du paramètre en octets (ce nombre ne s'inclut pas). Peut valoir zéro. En cas particulier, -1 indique une valeur NULL du paramètre.
n
La valeur du paramètre, dans le format indiqué par le code format
associé.
n
est la longueur ci-dessus.
Après le dernier paramètre, les champs suivants apparaissent :
Le nombre de codes formats des colonnes de résultat
(dénoté par R
ci-dessous).
Ce nombre peut valoir zéro pour indiquer qu'il n'y a pas de colonnes
de résultats ou que les colonnes de résultats devraient toutes utiliser
le format par défaut (texte) ; ou un, auquel cas le code format
spécifié est appliqué à toutes les colonnes du résultat (s'il y en
a) ; ou il peut être égal au nombre réel de colonnes résultats
de la requête.
R
]Les codes format des colonnes du résultat. Il n'existe que deux possibilités : zéro pour texte, un pour binaire.
Identifie le message comme un indicateur de fin de Bind.
Longueur du contenu du message en octets, longueur inclue.
Longueur du contenu du message en octets, longueur inclue.
Le code de demande d'annulation. La valeur est choisie pour contenir
1234
sur les 16 bits les plus significatifs, et
5678
sur 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 de protocole.)
L'identifiant de processus du backend cible.
La clé secrète du backend cible.
Identifie le message comme une commande Close.
Longueur du contenu du message en octets, longueur inclue.
'S
' pour fermer une requête préparée ; ou
'P
' pour fermer un portail.
Le nom de la requête préparée ou du portail à fermer (une chaîne vide sélectionne la requête préparée ou le portail non nommé).
Identifie le message comme un indicateur de fin de Close.
Longueur du contenu du message en octets, longueur inclue.
Identifie le message comme une réponse de fin de commande.
Longueur du contenu du message en octets, longueur inclue.
La balise de la commande. C'est habituellement un mot simple qui identifie la commande SQL terminée.
Pour une commande INSERT
, la balise est
INSERT
, où
oid
lignes
lignes
correspond au nombre de lignes
insérées. oid
était l'identifiant d'objet
de la ligne insérée si lignes
valait 1
et que la table cible avait des OID, mais les colonnes systèmes OID
ne sont plus supportées ; de ce fait,
oid
est toujours à 0.
Pour une commande DELETE
, la balise est
DELETE
où
lignes
lignes
correspond au nombre de lignes
supprimées.
Pour une commande UPDATE
, la balise est
UPDATE
où
lignes
lignes
correspond au nombre de lignes mises
à jour.
Pour une commande MERGE
, la balise est
MERGE
où
lignes
lignes
correspond au nombre de lignes insérées,
mises à jour ou supprimées.
Pour une commande SELECT
ou CREATE TABLE
AS
, la balise est SELECT
où lignes
lignes
correspond au nombre de lignes
récupérées.
Pour une commande MOVE
, la balise est
MOVE
où
lignes
lignes
correspond au nombre de lignes de
déplacement du curseur.
Pour une commande FETCH
, la balise est
FETCH
où
lignes
lignes
est le nombre de lignes qui ont été
récupérées du curseur.
Pour une commande COPY
, la balise est
COPY
où
lignes
lignes
est le nombre de lignes copiées.
(Note : le nombre de lignes apparaît seulement dans
PostgreSQL 8.2 et les versions ultérieures.)
Identifie le message comme des données COPY
.
Longueur du contenu du message en octets, longueur inclue.
n
Données qui forment une partie d'un flux de données
COPY
. Les messages envoyés à partir du backend
correspondront toujours à des lignes de données simples, mais les
messages envoyés par les clients pourraient diviser le flux de
données de façon arbitraire.
Identifie le message comme un indicateur de fin de
COPY
.
Longueur du contenu du message en octets, longueur inclue.
Identifie le message comme un indicateur d'échec de
COPY
.
Longueur du contenu du message en octets, longueur inclue.
Un message d'erreur à rapporter comme cause de l'échec.
Identifie le message comme une réponse Start Copy In. Le client doit
maintenant envoyer des données copy-in
(s'il n'est
pas préparé à le faire, envoie un message CopyFail).
Longueur du contenu du message en octets, longueur inclue.
0 indique que le format global de COPY
est du
texte (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 global de copie est binaire (similaire au
format DataRow).
Voir COPY pour plus d'informations.
Le nombre de colonnes dans les données à copier
(dénoté N
ci-dessous).
N
]Les codes format à utiliser pour chaque colonne. Il n'y a que deux possibilités : zéro pour texte, un pour binaire. Tous doivent être à zéro pour que le format de copie global soit du texte.
Identifie le message comme une réponse Start Copy Out.
Ce message sera suivi par les données copy-out
.
Longueur du contenu du message en octets, longueur inclue.
0 indique que le format global de COPY
est du texte
(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 global de
copie est binaire (similaire au format DataRow). Voir
COPY pour plus d'informations.
Le nombre de colonnes des données à copier
(dénoté N
ci-dessous).
N
]Les codes format à utiliser pour chaque colonne. Il n'y a que deux possibilités : zéro pour texte, un pour binaire. Ils doivent être tous à zéro pour que le format global de copie soit du texte.
Identifie le message comme une réponse Start Copy Both. Ce message est utilisé uniquement pour la réplication en flux.
Longueur du contenu du message en octets, longueur inclue.
0 indique que le format global de COPY
est du texte
(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 global de
copie est binaire (similaire au format DataRow). Voir
COPY pour plus d'informations.
Le nombre de colonnes dans les données à copier
(dénoté N
ci-dessous).
N
]Les codes format à utiliser pour chaque colonne. Il n'y a que deux possibilités : zéro pour texte, un pour binaire. Ils doivent être tous à zéro pour que le format global de copie soit du texte.
Identifie le message comme une ligne de données.
Longueur du contenu du message en octets, longueur inclue.
Le nombre de valeurs de colonnes (potentiellement zéro).
Ensuite, la paire de champs suivants apparaît pour chaque colonne :
La longueur de la valeur de la colonne, en octets (ce décompte ne s'inclue pas lui-même). Peut valoir zéro. Cas particulier, -1 indique une valeur de colonne NULL.
n
La valeur de la colonne, dans le format indiqué par le code format
associé. n
est la longueur ci-dessus.
Identifie le message comme une commande Describe.
Longueur du contenu du message en octets, longueur inclue.
'S
' pour décrire une requête préparée ; ou
'P
' pour décrire un portail.
Le nom de la requête préparée ou du portail à décrire (une chaîne vide sélectionne la requête préparée ou le portail non nommé).
Identifie le message comme une réponse à une chaîne vide de requête. (Cela se substitue à CommandComplete.)
Longueur du contenu du message en octets, longueur inclue.
Identifie le message comme une erreur.
Longueur du contenu du message en octets, longueur inclue.
Le corps du message consiste en un ou plusieurs champs identifiés, suivi par un octet zéro comme terminaison. Les champs peuvent apparaître dans n'importe quel ordre. Pour chaque champ, il existe ce qui suit :
Un code identifiant le type de champ ; si zéro, c'est le message de terminaison, et aucune chaîne ne suit. Les types de champs actuellement définis sont listés dans Section 55.8. Comme plus de types de champs pourraient être ajoutés dans le futur, les clients devraient ignorer silencieusement les champs dont le type n'est pas reconnu.
La valeur du champ.
Identifie le message comme une commande Execute.
Longueur du contenu du message en octets, longueur inclue.
Le nom du portail à exécuter (une chaîne vide sélectionne le portail non nommé).
Nombre maximum de lignes à renvoyer si le portail contient une requête qui renvoie des lignes (ignoré sinon). Zéro indique « pas de limite ».
Identifie le message comme une commande Flush.
Longueur du contenu du message en octets, longueur inclue.
Identifie le message comme un appel de fonction.
Longueur du contenu du message en octets, longueur inclue.
Indique l'identifiant d'objet de la fonction à appeler.
Le nombre de codes format des arguments
(dénoté C
ci-dessous).
Ce nombre peut valoir zéro pour indiquer qu'il n'y a pas d'arguments
ou que tous les arguments utilisent le format par défaut (texte) ;
ou un, auquel cas le code format spécifié est appliqué à tous les
arguments ; ou être égal au nombre réel d'arguments.
C
]Les codes formats des arguments. Il n'existe que deux possibilités : zéro pour texte, un pour binaire.
Indique le nombre d'arguments à fournir à la fonction.
Ensuite, la paire suivant de champs apparaît pour chaque argument :
La longueur de la valeur de l'argument, en octets (ce décompte ne s'inclue pas lui-même). Peut valoir zéro. Cas particulier, -1 indique une valeur de colonne NULL.
n
La valeur de l'argument, dans le format indiqué par le code format
associé.
n
est la longueur ci-dessus.
Après le dernier argument, le champ suivant apparaît :
Le code format pour le résultat de la fonction. Il n'existe que deux possibilités : 0 pour texte, 1 pour binaire.
Identifie le message comme un résultat d'appel de fonction.
Longueur du contenu du message en octets, longueur inclue.
La longueur du résultat de la fonction, en octets (ce décompte ne s'inclue pas lui-même). Peut valoir zéro. Cas particulier, -1 indique une valeur de colonne NULL.
n
La valeur du résultat de la fonction, dans le format indiqué par le
code format associé.
n
est la longueur ci-dessus.
Longueur du contenu du message en octets, longueur inclue.
Le code de demande de chiffrement GSSAPI. La valeur
est choisie pour contenir 1234
sur les 16 bits les
plus significatifs, et 5680
sur les 16 bits les
moins significatifs. (Pour éviter de la confusion, ce code ne doit pas
être le même que le numéro de version du protocole.)
Identifie le message comme une réponse GSSAPI ou SSPI. Notez que ceci est aussi utilisé pour les messages de réponse SASL et mot de passe. Le type exact du message peut être déduit du contexte.
Longueur du contenu du message en octets, longueur inclue.
n
Données spécifiques du message GSSAPI/SSPI.
Identifie le message comme un message de négociation de version du protocole.
Longueur du contenu du message en octets, longueur inclue.
Version mineure la plus récente supportée par le serveur pour la version majeure réclamée par le client.
Nombre d'options du protocole non reconnues par le serveur.
Puis, pour l'option de protocole non reconnue par le serveur, il y a ce qui suit :
Le nom de l'option.
Identifie le message comme un indicateur d'absence de données.
Longueur du contenu du message en octets, longueur inclue.
Identifie le message comme une information.
Longueur du contenu du message en octets, longueur inclue.
Le corps du message consiste en un ou plusieurs champs identifiés, suivi par un octet zéro comme terminaison. Les champs peuvent apparaître dans n'importe quel ordre. Pour chaque champ, il existe ce qui suit :
Un code identifiant le type de champs ; si zéro, ceci est le message de terminaison et aucune chaîne de caractères ne suit. Les types de champs actuellement définis sont listés dans Section 55.8. Comme plus de types de champs pourraient être ajoutés dans le futur, les clients devraient ignorer silencieusement les champs dont le type leur est inconnu.
La valeur du champ.
Identifie le message comme une réponse à une notification.
Longueur du contenu du message en octets, longueur inclue.
L'identifiant du processus backend notifiant.
Le nom du canal où la notification a été levée.
La « charge » passée par le processus notifiant.
Identifie le message comme une description de paramètre.
Longueur du contenu du message en octets, longueur inclue.
Le nombre de paramètres utilisés par la requête (peut valoir zéro).
Ensuite, pour chaque paramètre, il y a ce qui suit :
Indique l'identifiant d'objet du type de données du paramètre.
Identifie le message comme un rapport de statut d'un paramètre.
Longueur du contenu du message en octets, longueur inclue.
Le nom du paramètre.
La valeur actuelle de ce paramètre.
Identifie le message comme une commande Parse.
Longueur du contenu du message en octets, longueur inclue.
Le nom de la requête préparée de destination (une chaîne vide sélectionne la requête préparée non nommée).
La chaîne de requête à analyser.
Le nombre de types de données des paramètres (peut valoir zéro). Notez que cela n'est pas une indication du nombre de paramètres qui pourraient apparaître dans la requête de chaîne, seulement le nombre de types que le client souhaite pré-déclarer.
Ensuite, pour chaque paramètre, il y a ce qui suit :
Indique l'identifiant d'objet du type de données du paramètre. Placer un zéro ici est équivalent à laisser le type sans spécification.
Identifie le message comme un indicateur de fin de Parse.
Longueur du contenu du message en octets, longueur inclue.
Identifie le message comme une réponse de mot de passe. Notez que c'est aussi utilisé pour les messages de réponse pour GSSAPI, SSPI et SASL. Le type exact de message peut être déduit du contexte.
Longueur du contenu du message en octets, longueur inclue.
Le mot de passe (chiffré si demandé).
Identifie le message comme un indicateur de portal-suspended. Notez que ceci survient uniquement si la limite de lignes a été atteint pour un message Execute.
Longueur du contenu du message en octets, longueur inclue.
Identifie le message comme une simple requête.
Longueur du contenu du message en octets, longueur inclue.
La requête elle-même.
Identifie le type de message. ReadyForQuery est envoyé quand le backend est prêt pour un nouveau cycle de requête.
Longueur du contenu du message en octets, longueur inclue.
Indicateur du statut de transaction du backend. Les valeurs possibles
sont 'I
' si inactif (et pas dans un bloc de
transaction) ; 'T
' si dans un bloc de
transaction ; ou 'E
' si dans un bloc de
transaction en échec (les requêtes seront rejetées jusqu'à la fin du
bloc).
Identifie le message comme une description de ligne.
Longueur du contenu du message en octets, longueur inclue.
Indique le nombre de champs dans une ligne (peut valoir zéro).
Ensuite, pour chaque champ, il y a ce qui suit :
Le nom du champ.
Si le champ peut être identifié comme une colonne d'une table précise, l'identifiant d'objet de la table ; sinon zéro.
Si le champ peut être identifié comme une colonne d'une table précise, le numéro de la colonne ; sinon zéro.
L'identifiant d'objet du type de données du champ.
La taille du type de données (voir pg_type.typlen
).
Notez que les valeurs négatives désignent des types à taille variable.
Le modifieur du type (voir pg_attribute.atttypmod
).
La signification du modifieur dépend du type.
Le code format en cours d'utilisation pour le champ. Actuellement, ce sera soit zéro (texte) soit un (binaire). Dans un RowDescription renvoyé à partir de la variante requête de Describe, le code format n'est pas encore connu et sera toujours zéro.
Identifie le message comme une réponse SASL initiale. Notez que ce message est aussi utilisé pour les messages de réponse de GSSAPI, SSPI et mot de passe. Le type exact de message est déduit du contexte.
Longueur du contenu du message en octets, longueur inclue.
Nom du mécanisme d'authentification SASL que le client a sélectionné.
Longueur du "Initial Client Response" spécifique au mécanisme SASL,
ou -1 en cas d'absence de Initial Response
.
n
"Initial Response" spécifique au mécanisme SASL.
Identifie le message comme une réponse SASL. Notez que ce message est aussi utilisé par les messages réponses de GSSAPI, SSPI et mot de passe. Le type exact de message peut être déduit du contexte.
Longueur du contenu du message en octets, longueur inclue.
n
Données du message spécifique au mécanisme SASL.
Longueur du contenu du message en octets, longueur inclue.
Le code de demande de chiffrement SSL. La valeur
est choisie pour contenir 1234
sur les 16 bits les
plus significatifs, et 5679
sur les 16 bits les
moins significatifs. (Pour éviter de la confusion, ce code ne doit pas
être le même que le numéro de version du protocole.)
Longueur du contenu du message en octets, longueur inclue.
Le numéro de version du protocole. Les 16 bits les plus significatifs sont le numéro de version majeure (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/valeur de paramètre. Un octet zéro est requis comme terminaison après
la dernière paire nom/valeur. Les paramètres peuvent apparaître dans
n'importe quel ordre. user
est requis, les autres sont
optionnels. Chaque paramètre est spécifié ainsi :
Le nom du paramètre. Actuellement, les noms reconnus sont :
user
Le nom de l'utilisateur pour la connexion à la base. Requis, pas de valeur par défaut.
database
La base de données où se connecter. Par défaut, le nom de l'utilisateur.
options
Arguments de la ligne de commande pour le backend. (C'est abandonné
au profit de la configuration de paramètres individuels.) Les
espaces dans cette chaîne permettent de séparer les arguments,
à moins qu'ils ne soient échappés avec un caractère antislash
(\
) ; écrire \\
pour
représenter un antislash litéral.
replication
Utilisé pour se connecter mode de réplication en flux, où un petit
ensemble de commandes de réplication peuvent être exécutées au lieu
de requêtes SQL. Les valeurs peuvent être true
,
false
ou database
, et la
valeur par défaut est false
. Voir Section 55.4 pour plus de détails.
En plus de tout cela, d'autres paramètres pourraient être listés. Les
noms de paramètre commençant avec _pq_.
sont
réservés pour une utilisation en tant qu'extensions du protocole,
alors que les autres sont traités comme des paramètres d'exécution
à configurer au démarrage du backend. De telles configurations seront
appliquées au démarrage du serveur (après analyse des arguments en
ligne de commande s'il y en a) et agiront comme valeurs par défaut
de la session.
La valeur du paramètre.
Identifie le message comme une commande Sync.
Longueur du contenu du message en octets, longueur inclue.
Identifie le message comme une fin de session.
Longueur du contenu du message en octets, longueur inclue.