1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
5
>Message Formats</TITLE
8
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
10
HREF="mailto:pgsql-docs@postgresql.org"><LINK
12
TITLE="PostgreSQL 9.1beta1 Documentation"
13
HREF="index.html"><LINK
15
TITLE="Frontend/Backend Protocol"
16
HREF="protocol.html"><LINK
18
TITLE="Message Data Types"
19
HREF="protocol-message-types.html"><LINK
21
TITLE="Error and Notice Message Fields"
22
HREF="protocol-error-fields.html"><LINK
25
HREF="stylesheet.css"><META
26
HTTP-EQUIV="Content-Type"
27
CONTENT="text/html; charset=ISO-8859-1"><META
29
CONTENT="2011-04-27T21:20:33"></HEAD
35
SUMMARY="Header navigation table"
47
>PostgreSQL 9.1beta1 Documentation</A
56
TITLE="Message Data Types"
57
HREF="protocol-message-types.html"
66
TITLE="Frontend/Backend Protocol"
74
>Chapter 46. Frontend/Backend Protocol</TD
80
TITLE="Frontend/Backend Protocol"
89
TITLE="Error and Notice Message Fields"
90
HREF="protocol-error-fields.html"
104
NAME="PROTOCOL-MESSAGE-FORMATS"
105
>46.5. Message Formats</A
108
>This section describes the detailed format of each message. Each is marked to
109
indicate that it can be sent by a frontend (F), a backend (B), or both
111
Notice that although each message includes a byte count at the beginning,
112
the message format is defined so that the message end can be found without
113
reference to the byte count. This aids validity checking. (The CopyData
114
message is an exception, because it forms part of a data stream; the contents
115
of any individual CopyData message cannot be interpretable on their own.)</P
122
>AuthenticationOk (B)</DT
134
> Identifies the message as an authentication request.</P
140
> Length of message contents in bytes, including self.</P
146
> Specifies that the authentication was successful.</P
153
>AuthenticationKerberosV5 (B)</DT
165
> Identifies the message as an authentication request.</P
171
> Length of message contents in bytes, including self.</P
177
> Specifies that Kerberos V5 authentication is required.</P
184
>AuthenticationCleartextPassword (B)</DT
196
> Identifies the message as an authentication request.</P
202
> Length of message contents in bytes, including self.</P
208
> Specifies that a clear-text password is required.</P
215
>AuthenticationMD5Password (B)</DT
227
> Identifies the message as an authentication request.</P
233
> Length of message contents in bytes, including self.</P
239
> Specifies that an MD5-encrypted password is required.</P
245
> The salt to use when encrypting the password.</P
252
>AuthenticationSCMCredential (B)</DT
264
> Identifies the message as an authentication request.</P
270
> Length of message contents in bytes, including self.</P
276
> Specifies that an SCM credentials message is required.</P
283
>AuthenticationGSS (B)</DT
295
> Identifies the message as an authentication request.</P
301
> Length of message contents in bytes, including self.</P
307
> Specifies that GSSAPI authentication is required.</P
314
>AuthenticationSSPI (B)</DT
326
> Identifies the message as an authentication request.</P
332
> Length of message contents in bytes, including self.</P
338
> Specifies that SSPI authentication is required.</P
345
>AuthenticationGSSContinue (B)</DT
357
> Identifies the message as an authentication request.</P
363
> Length of message contents in bytes, including self.</P
369
> Specifies that this message contains GSSAPI or SSPI data.</P
380
> GSSAPI or SSPI authentication data.</P
387
>BackendKeyData (B)</DT
399
> Identifies the message as cancellation key data.
400
The frontend must save these values if it wishes to be
401
able to issue CancelRequest messages later.</P
407
> Length of message contents in bytes, including self.</P
413
> The process ID of this backend.</P
419
> The secret key of this backend.</P
438
> Identifies the message as a Bind command.</P
444
> Length of message contents in bytes, including self.</P
450
> The name of the destination portal
451
(an empty string selects the unnamed portal).</P
457
> The name of the source prepared statement
458
(an empty string selects the unnamed prepared statement).</P
464
> The number of parameter format codes that follow
471
This can be zero to indicate that there are no parameters
472
or that the parameters all use the default format (text);
473
or one, in which case the specified format code is applied
474
to all parameters; or it can equal the actual number of
486
> The parameter format codes. Each must presently be
487
zero (text) or one (binary).</P
493
> The number of parameter values that follow (possibly zero).
494
This must match the number of parameters needed by the query.</P
499
Next, the following pair of fields appear for each parameter:
509
> The length of the parameter value, in bytes (this count
510
does not include itself). Can be zero.
511
As a special case, -1 indicates a NULL parameter value.
512
No value bytes follow in the NULL case.</P
523
> The value of the parameter, in the format indicated by the
524
associated format code.
530
> is the above length.</P
535
After the last parameter, the following fields appear:
545
> The number of result-column format codes that follow
552
This can be zero to indicate that there are no result columns
553
or that the result columns should all use the default format
555
or one, in which case the specified format code is applied
556
to all result columns (if any); or it can equal the actual
557
number of result columns of the query.</P
568
> The result-column format codes. Each must presently be
569
zero (text) or one (binary).</P
576
>BindComplete (B)</DT
588
> Identifies the message as a Bind-complete indicator.</P
594
> Length of message contents in bytes, including self.</P
601
>CancelRequest (F)</DT
613
> Length of message contents in bytes, including self.</P
619
> The cancel request code. The value is chosen to contain
623
> in the most significant 16 bits, and <TT
627
least 16 significant bits. (To avoid confusion, this code
628
must not be the same as any protocol version number.)</P
634
> The process ID of the target backend.</P
640
> The secret key for the target backend.</P
659
> Identifies the message as a Close command.</P
665
> Length of message contents in bytes, including self.</P
674
>' to close a prepared statement; or
678
>' to close a portal.</P
684
> The name of the prepared statement or portal to close
685
(an empty string selects the unnamed prepared statement
693
>CloseComplete (B)</DT
705
> Identifies the message as a Close-complete indicator.</P
711
> Length of message contents in bytes, including self.</P
718
>CommandComplete (B)</DT
730
> Identifies the message as a command-completed response.</P
736
> Length of message contents in bytes, including self.</P
742
> The command tag. This is usually a single
743
word that identifies which SQL command was completed.
749
> command, the tag is
770
> is the number of rows
777
of the inserted row if <TT
783
and the target table has OIDs;
795
> command, the tag is
810
> is the number of rows deleted.
816
> command, the tag is
831
> is the number of rows updated.
841
command, the tag is <TT
855
> is the number of rows retrieved.
861
> command, the tag is
876
> is the number of rows the
877
cursor's position has been changed by.
883
> command, the tag is
898
> is the number of rows that
899
have been retrieved from the cursor.
905
> command, the tag is
920
> is the number of rows copied.
921
(Note: the row count appears only in
933
>CopyData (F & B)</DT
945
> Identifies the message as <TT
954
> Length of message contents in bytes, including self.</P
965
> Data that forms part of a <TT
968
> data stream. Messages sent
969
from the backend will always correspond to single data rows,
970
but messages sent by frontends might divide the data stream
978
>CopyDone (F & B)</DT
990
> Identifies the message as a <TT
993
>-complete indicator.</P
999
> Length of message contents in bytes, including self.</P
1012
CLASS="VARIABLELIST"
1018
> Identifies the message as a <TT
1021
>-failure indicator.</P
1027
> Length of message contents in bytes, including self.</P
1033
> An error message to report as the cause of failure.</P
1040
>CopyInResponse (B)</DT
1046
CLASS="VARIABLELIST"
1052
> Identifies the message as a Start Copy In response.
1053
The frontend must now send copy-in data (if not
1054
prepared to do so, send a CopyFail message).</P
1060
> Length of message contents in bytes, including self.</P
1066
> 0 indicates the overall <TT
1069
> format is textual (rows
1070
separated by newlines, columns separated by separator
1072
1 indicates the overall copy format is binary (similar
1075
HREF="sql-copy.html"
1078
for more information.</P
1084
> The number of columns in the data to be copied
1101
> The format codes to be used for each column.
1102
Each must presently be zero (text) or one (binary).
1103
All must be zero if the overall copy format is textual.</P
1110
>CopyOutResponse (B)</DT
1116
CLASS="VARIABLELIST"
1122
> Identifies the message as a Start Copy Out response.
1123
This message will be followed by copy-out data.</P
1129
> Length of message contents in bytes, including self.</P
1135
> 0 indicates the overall <TT
1139
is textual (rows separated by newlines, columns
1140
separated by separator characters, etc). 1 indicates
1141
the overall copy format is binary (similar to DataRow
1143
HREF="sql-copy.html"
1145
> for more information.</P
1151
> The number of columns in the data to be copied
1168
> The format codes to be used for each column.
1169
Each must presently be zero (text) or one (binary).
1170
All must be zero if the overall copy format is textual.</P
1177
>CopyBothResponse (B)</DT
1183
CLASS="VARIABLELIST"
1189
> Identifies the message as a Start Copy Both response.
1190
This message is used only for Streaming Replication.</P
1196
> Length of message contents in bytes, including self.</P
1202
> 0 indicates the overall <TT
1206
is textual (rows separated by newlines, columns
1207
separated by separator characters, etc). 1 indicates
1208
the overall copy format is binary (similar to DataRow
1210
HREF="sql-copy.html"
1212
> for more information.</P
1218
> The number of columns in the data to be copied
1235
> The format codes to be used for each column.
1236
Each must presently be zero (text) or one (binary).
1237
All must be zero if the overall copy format is textual.</P
1250
CLASS="VARIABLELIST"
1256
> Identifies the message as a data row.</P
1262
> Length of message contents in bytes, including self.</P
1268
> The number of column values that follow (possibly zero).</P
1273
Next, the following pair of fields appear for each column:
1277
CLASS="VARIABLELIST"
1283
> The length of the column value, in bytes (this count
1284
does not include itself). Can be zero.
1285
As a special case, -1 indicates a NULL column value.
1286
No value bytes follow in the NULL case.</P
1297
> The value of the column, in the format indicated by the
1298
associated format code.
1304
> is the above length.</P
1317
CLASS="VARIABLELIST"
1323
> Identifies the message as a Describe command.</P
1329
> Length of message contents in bytes, including self.</P
1338
>' to describe a prepared statement; or
1342
>' to describe a portal.</P
1348
> The name of the prepared statement or portal to describe
1349
(an empty string selects the unnamed prepared statement
1357
>EmptyQueryResponse (B)</DT
1363
CLASS="VARIABLELIST"
1369
> Identifies the message as a response to an empty query string.
1370
(This substitutes for CommandComplete.)</P
1376
> Length of message contents in bytes, including self.</P
1383
>ErrorResponse (B)</DT
1389
CLASS="VARIABLELIST"
1395
> Identifies the message as an error.</P
1401
> Length of message contents in bytes, including self.</P
1406
The message body consists of one or more identified fields,
1407
followed by a zero byte as a terminator. Fields can appear in
1408
any order. For each field there is the following:
1412
CLASS="VARIABLELIST"
1418
> A code identifying the field type; if zero, this is
1419
the message terminator and no string follows.
1420
The presently defined field types are listed in
1422
HREF="protocol-error-fields.html"
1425
Since more field types might be added in future,
1426
frontends should silently ignore fields of unrecognized
1433
> The field value.</P
1446
CLASS="VARIABLELIST"
1452
> Identifies the message as an Execute command.</P
1458
> Length of message contents in bytes, including self.</P
1464
> The name of the portal to execute
1465
(an empty string selects the unnamed portal).</P
1471
> Maximum number of rows to return, if portal contains
1472
a query that returns rows (ignored otherwise). Zero
1489
CLASS="VARIABLELIST"
1495
> Identifies the message as a Flush command.</P
1501
> Length of message contents in bytes, including self.</P
1508
>FunctionCall (F)</DT
1514
CLASS="VARIABLELIST"
1520
> Identifies the message as a function call.</P
1526
> Length of message contents in bytes, including self.</P
1532
> Specifies the object ID of the function to call.</P
1538
> The number of argument format codes that follow
1545
This can be zero to indicate that there are no arguments
1546
or that the arguments all use the default format (text);
1547
or one, in which case the specified format code is applied
1548
to all arguments; or it can equal the actual number of
1560
> The argument format codes. Each must presently be
1561
zero (text) or one (binary).</P
1567
> Specifies the number of arguments being supplied to the
1573
Next, the following pair of fields appear for each argument:
1577
CLASS="VARIABLELIST"
1583
> The length of the argument value, in bytes (this count
1584
does not include itself). Can be zero.
1585
As a special case, -1 indicates a NULL argument value.
1586
No value bytes follow in the NULL case.</P
1597
> The value of the argument, in the format indicated by the
1598
associated format code.
1604
> is the above length.</P
1609
After the last argument, the following field appears:
1613
CLASS="VARIABLELIST"
1619
> The format code for the function result. Must presently be
1620
zero (text) or one (binary).</P
1627
>FunctionCallResponse (B)</DT
1633
CLASS="VARIABLELIST"
1639
> Identifies the message as a function call result.</P
1645
> Length of message contents in bytes, including self.</P
1651
> The length of the function result value, in bytes (this count
1652
does not include itself). Can be zero.
1653
As a special case, -1 indicates a NULL function result.
1654
No value bytes follow in the NULL case.</P
1665
> The value of the function result, in the format indicated by
1666
the associated format code.
1672
> is the above length.</P
1685
CLASS="VARIABLELIST"
1691
> Identifies the message as a no-data indicator.</P
1697
> Length of message contents in bytes, including self.</P
1704
>NoticeResponse (B)</DT
1710
CLASS="VARIABLELIST"
1716
> Identifies the message as a notice.</P
1722
> Length of message contents in bytes, including self.</P
1727
The message body consists of one or more identified fields,
1728
followed by a zero byte as a terminator. Fields can appear in
1729
any order. For each field there is the following:
1733
CLASS="VARIABLELIST"
1739
> A code identifying the field type; if zero, this is
1740
the message terminator and no string follows.
1741
The presently defined field types are listed in
1743
HREF="protocol-error-fields.html"
1746
Since more field types might be added in future,
1747
frontends should silently ignore fields of unrecognized
1754
> The field value.</P
1761
>NotificationResponse (B)</DT
1767
CLASS="VARIABLELIST"
1773
> Identifies the message as a notification response.</P
1779
> Length of message contents in bytes, including self.</P
1785
> The process ID of the notifying backend process.</P
1791
> The name of the channel that the notify has been raised on.</P
1800
> string passed from the notifying process.</P
1807
>ParameterDescription (B)</DT
1813
CLASS="VARIABLELIST"
1819
> Identifies the message as a parameter description.</P
1825
> Length of message contents in bytes, including self.</P
1831
> The number of parameters used by the statement
1837
Then, for each parameter, there is the following:
1841
CLASS="VARIABLELIST"
1847
> Specifies the object ID of the parameter data type.</P
1854
>ParameterStatus (B)</DT
1860
CLASS="VARIABLELIST"
1866
> Identifies the message as a run-time parameter status report.</P
1872
> Length of message contents in bytes, including self.</P
1878
> The name of the run-time parameter being reported.</P
1884
> The current value of the parameter.</P
1897
CLASS="VARIABLELIST"
1903
> Identifies the message as a Parse command.</P
1909
> Length of message contents in bytes, including self.</P
1915
> The name of the destination prepared statement
1916
(an empty string selects the unnamed prepared statement).</P
1922
> The query string to be parsed.</P
1928
> The number of parameter data types specified
1929
(can be zero). Note that this is not an indication of
1930
the number of parameters that might appear in the
1931
query string, only the number that the frontend wants to
1932
prespecify types for.</P
1937
Then, for each parameter, there is the following:
1941
CLASS="VARIABLELIST"
1947
> Specifies the object ID of the parameter data type.
1948
Placing a zero here is equivalent to leaving the type
1956
>ParseComplete (B)</DT
1962
CLASS="VARIABLELIST"
1968
> Identifies the message as a Parse-complete indicator.</P
1974
> Length of message contents in bytes, including self.</P
1981
>PasswordMessage (F)</DT
1987
CLASS="VARIABLELIST"
1993
> Identifies the message as a password response. Note that
1994
this is also used for GSSAPI and SSPI response messages
1995
(which is really a design error, since the contained data
1996
is not a null-terminated string in that case, but can be
1997
arbitrary binary data).</P
2003
> Length of message contents in bytes, including self.</P
2009
> The password (encrypted, if requested).</P
2016
>PortalSuspended (B)</DT
2022
CLASS="VARIABLELIST"
2028
> Identifies the message as a portal-suspended indicator.
2029
Note this only appears if an Execute message's row-count limit
2036
> Length of message contents in bytes, including self.</P
2049
CLASS="VARIABLELIST"
2055
> Identifies the message as a simple query.</P
2061
> Length of message contents in bytes, including self.</P
2067
> The query string itself.</P
2074
>ReadyForQuery (B)</DT
2080
CLASS="VARIABLELIST"
2086
> Identifies the message type. ReadyForQuery is sent
2087
whenever the backend is ready for a new query cycle.</P
2093
> Length of message contents in bytes, including self.</P
2099
> Current backend transaction status indicator.
2100
Possible values are '<TT
2104
a transaction block); '<TT
2107
>' if in a transaction
2111
>' if in a failed transaction
2112
block (queries will be rejected until block is ended).</P
2119
>RowDescription (B)</DT
2125
CLASS="VARIABLELIST"
2131
> Identifies the message as a row description.</P
2137
> Length of message contents in bytes, including self.</P
2143
> Specifies the number of fields in a row (can be zero).</P
2148
Then, for each field, there is the following:
2152
CLASS="VARIABLELIST"
2158
> The field name.</P
2164
> If the field can be identified as a column of a specific
2165
table, the object ID of the table; otherwise zero.</P
2171
> If the field can be identified as a column of a specific
2172
table, the attribute number of the column; otherwise zero.</P
2178
> The object ID of the field's data type.</P
2184
> The data type size (see <TT
2188
Note that negative values denote variable-width types.</P
2194
> The type modifier (see <TT
2196
>pg_attribute.atttypmod</TT
2198
The meaning of the modifier is type-specific.</P
2204
> The format code being used for the field. Currently will
2205
be zero (text) or one (binary). In a RowDescription
2206
returned from the statement variant of Describe, the
2207
format code is not yet known and will always be zero.</P
2220
CLASS="VARIABLELIST"
2226
> Length of message contents in bytes, including self.</P
2229
>Int32(80877103)</DT
2235
> request code. The value is chosen to contain
2239
> in the most significant 16 bits, and <TT
2243
least 16 significant bits. (To avoid confusion, this code
2244
must not be the same as any protocol version number.)</P
2251
>StartupMessage (F)</DT
2257
CLASS="VARIABLELIST"
2263
> Length of message contents in bytes, including self.</P
2269
> The protocol version number. The most significant 16 bits are
2270
the major version number (3 for the protocol described here).
2271
The least significant 16 bits are the minor version number
2272
(0 for the protocol described here).</P
2277
The protocol version number is followed by one or more pairs of
2278
parameter name and value strings. A zero byte is required as a
2279
terminator after the last name/value pair.
2280
Parameters can appear in any
2284
> is required, others are optional.
2285
Each parameter is specified as:
2289
CLASS="VARIABLELIST"
2295
> The parameter name. Currently recognized names are:
2300
CLASS="VARIABLELIST"
2309
> The database user name to connect as. Required;
2310
there is no default.</P
2319
> The database to connect to. Defaults to the user name.</P
2328
> Command-line arguments for the backend. (This is
2329
deprecated in favor of setting individual run-time
2336
In addition to the above, any run-time parameter that can be
2337
set at backend start time might be listed. Such settings
2338
will be applied during backend start (after parsing the
2339
command-line options if any). The values will act as
2340
session defaults.</P
2346
> The parameter value.</P
2359
CLASS="VARIABLELIST"
2365
> Identifies the message as a Sync command.</P
2371
> Length of message contents in bytes, including self.</P
2384
CLASS="VARIABLELIST"
2390
> Identifies the message as a termination.</P
2396
> Length of message contents in bytes, including self.</P
2410
SUMMARY="Footer navigation table"
2421
HREF="protocol-message-types.html"
2439
HREF="protocol-error-fields.html"
2449
>Message Data Types</TD
2455
HREF="protocol.html"
2463
>Error and Notice Message Fields</TD
b'\\ No newline at end of file'
added
removed
doc/src/sgml/html/protocol-message-formats.html
