Debian Codegraph @

doc/src/sgml/protocol.sgml

raw
1 <!-- doc/src/sgml/protocol.sgml -->
2
3 <chapter id="protocol">
4 <title>Frontend/Backend Protocol</title>
5
6 <indexterm zone="protocol">
7 <primary>protocol</primary>
8 <secondary>frontend-backend</secondary>
9 </indexterm>
10
11 <para>
12 <productname>PostgreSQL</productname> uses a message-based protocol
13 for communication between frontends and backends (clients and servers).
14 The protocol is supported over <acronym>TCP/IP</acronym> and also over
15 Unix-domain sockets. Port number 5432 has been registered with IANA as
16 the customary TCP port number for servers supporting this protocol, but
17 in practice any non-privileged port number can be used.
18 </para>
19
20 <para>
21 This document describes version 3.2 of the protocol, introduced in
22 <productname>PostgreSQL</productname> version 18. The server and the libpq
23 client library are backwards compatible with protocol version 3.0,
24 implemented in <productname>PostgreSQL</productname> 7.4 and later.
25 </para>
26
27 <para>
28 In order to serve multiple clients efficiently, the server launches
29 a new <quote>backend</quote> process for each client.
30 In the current implementation, a new child
31 process is created immediately after an incoming connection is detected.
32 This is transparent to the protocol, however. For purposes of the
33 protocol, the terms <quote>backend</quote> and <quote>server</quote> are
34 interchangeable; likewise <quote>frontend</quote> and <quote>client</quote>
35 are interchangeable.
36 </para>
37
38 <sect1 id="protocol-overview">
39 <title>Overview</title>
40
41 <para>
42 The protocol has separate phases for startup and normal operation.
43 In the startup phase, the frontend opens a connection to the server
44 and authenticates itself to the satisfaction of the server. (This might
45 involve a single message, or multiple messages depending on the
46 authentication method being used.) If all goes well, the server then sends
47 status information to the frontend, and finally enters normal operation.
48 Except for the initial startup-request message, this part of the
49 protocol is driven by the server.
50 </para>
51
52 <para>
53 During normal operation, the frontend sends queries and
54 other commands to the backend, and the backend sends back query results
55 and other responses. There are a few cases (such as <command>NOTIFY</command>)
56 wherein the
57 backend will send unsolicited messages, but for the most part this portion
58 of a session is driven by frontend requests.
59 </para>
60
61 <para>
62 Termination of the session is normally by frontend choice, but can be
63 forced by the backend in certain cases. In any case, when the backend
64 closes the connection, it will roll back any open (incomplete) transaction
65 before exiting.
66 </para>
67
68 <para>
69 Within normal operation, SQL commands can be executed through either of
70 two sub-protocols. In the <quote>simple query</quote> protocol, the frontend
71 just sends a textual query string, which is parsed and immediately
72 executed by the backend. In the <quote>extended query</quote> protocol,
73 processing of queries is separated into multiple steps: parsing,
74 binding of parameter values, and execution. This offers flexibility
75 and performance benefits, at the cost of extra complexity.
76 </para>
77
78 <para>
79 Normal operation has additional sub-protocols for special operations
80 such as <command>COPY</command>.
81 </para>
82
83 <sect2 id="protocol-message-concepts">
84 <title>Messaging Overview</title>
85
86 <para>
87 All communication is through a stream of messages. The first byte of a
88 message identifies the message type, and the next four bytes specify the
89 length of the rest of the message (this length count includes itself, but
90 not the message-type byte). The remaining contents of the message are
91 determined by the message type. For historical reasons, the very first
92 message sent by the client (the startup message) has no initial
93 message-type byte.
94 </para>
95
96 <para>
97 To avoid losing synchronization with the message stream, both servers and
98 clients typically read an entire message into a buffer (using the byte
99 count) before attempting to process its contents. This allows easy
100 recovery if an error is detected while processing the contents. In
101 extreme situations (such as not having enough memory to buffer the
102 message), the receiver can use the byte count to determine how much
103 input to skip before it resumes reading messages.
104 </para>
105
106 <para>
107 Conversely, both servers and clients must take care never to send an
108 incomplete message. This is commonly done by marshaling the entire message
109 in a buffer before beginning to send it. If a communications failure
110 occurs partway through sending or receiving a message, the only sensible
111 response is to abandon the connection, since there is little hope of
112 recovering message-boundary synchronization.
113 </para>
114 </sect2>
115
116 <sect2 id="protocol-query-concepts">
117 <title>Extended Query Overview</title>
118
119 <para>
120 In the extended-query protocol, execution of SQL commands is divided
121 into multiple steps. The state retained between steps is represented
122 by two types of objects: <firstterm>prepared statements</firstterm> and
123 <firstterm>portals</firstterm>. A prepared statement represents the result of
124 parsing and semantic analysis of a textual query string.
125 A prepared statement is not in itself ready to execute, because it might
126 lack specific values for <firstterm>parameters</firstterm>. A portal represents
127 a ready-to-execute or already-partially-executed statement, with any
128 missing parameter values filled in. (For <command>SELECT</command> statements,
129 a portal is equivalent to an open cursor, but we choose to use a different
130 term since cursors don't handle non-<command>SELECT</command> statements.)
131 </para>
132
133 <para>
134 The overall execution cycle consists of a <firstterm>parse</firstterm> step,
135 which creates a prepared statement from a textual query string; a
136 <firstterm>bind</firstterm> step, which creates a portal given a prepared
137 statement and values for any needed parameters; and an
138 <firstterm>execute</firstterm> step that runs a portal's query. In the case of
139 a query that returns rows (<command>SELECT</command>, <command>SHOW</command>, etc.),
140 the execute step can be told to fetch only
141 a limited number of rows, so that multiple execute steps might be needed
142 to complete the operation.
143 </para>
144
145 <para>
146 The backend can keep track of multiple prepared statements and portals
147 (but note that these exist only within a session, and are never shared
148 across sessions). Existing prepared statements and portals are
149 referenced by names assigned when they were created. In addition,
150 an <quote>unnamed</quote> prepared statement and portal exist. Although these
151 behave largely the same as named objects, operations on them are optimized
152 for the case of executing a query only once and then discarding it,
153 whereas operations on named objects are optimized on the expectation
154 of multiple uses.
155 </para>
156 </sect2>
157
158 <sect2 id="protocol-format-codes">
159 <title>Formats and Format Codes</title>
160
161 <para>
162 Data of a particular data type might be transmitted in any of several
163 different <firstterm>formats</firstterm>. As of <productname>PostgreSQL</productname> 7.4
164 the only supported formats are <quote>text</quote> and <quote>binary</quote>,
165 but the protocol makes provision for future extensions. The desired
166 format for any value is specified by a <firstterm>format code</firstterm>.
167 Clients can specify a format code for each transmitted parameter value
168 and for each column of a query result. Text has format code zero,
169 binary has format code one, and all other format codes are reserved
170 for future definition.
171 </para>
172
173 <para>
174 The text representation of values is whatever strings are produced
175 and accepted by the input/output conversion functions for the
176 particular data type. In the transmitted representation, there is
177 no trailing null character; the frontend must add one to received
178 values if it wants to process them as C strings.
179 (The text format does not allow embedded nulls, by the way.)
180 </para>
181
182 <para>
183 Binary representations for integers use network byte order (most
184 significant byte first). For other data types consult the documentation
185 or source code to learn about the binary representation. Keep in mind
186 that binary representations for complex data types might change across
187 server versions; the text format is usually the more portable choice.
188 </para>
189 </sect2>
190
191 <sect2 id="protocol-versions">
192 <title>Protocol Versions</title>
193
194 <para>
195 The current, latest version of the protocol is version 3.2. However, for
196 backwards compatibility with old server versions and middleware that don't
197 support the version negotiation yet, libpq still uses protocol version 3.0
198 by default.
199 </para>
200
201 <para>
202 A single server can support multiple protocol versions. The initial
203 startup-request message tells the server which protocol version the client
204 is attempting to use. If the major version requested by the client is not
205 supported by the server, the connection will be rejected (for example,
206 this would occur if the client requested protocol version 4.0, which does
207 not exist as of this writing). If the minor version requested by the
208 client is not supported by the server (e.g., the client requests version
209 3.2, but the server supports only 3.0), the server may either reject the
210 connection or may respond with a NegotiateProtocolVersion message
211 containing the highest minor protocol version which it supports. The
212 client may then choose either to continue with the connection using the
213 specified protocol version or to abort the connection.
214 </para>
215
216 <para>
217 The protocol negotiation was introduced in
218 <productname>PostgreSQL</productname> version 9.3.21. Earlier versions
219 would reject the connection if the client requested a minor version that
220 was not supported by the server.
221 </para>
222
223 <para>
224 <xref linkend="protocol-versions-table"/> shows the currently supported
225 protocol versions.
226 </para>
227
228 <table id="protocol-versions-table">
229 <title>Protocol Versions</title>
230
231 <tgroup cols="3">
232 <thead>
233 <row>
234 <entry>Version</entry>
235 <entry>Supported by</entry>
236 <entry>Description</entry>
237 </row>
238 </thead>
239
240 <tbody>
241 <row>
242 <entry>3.2</entry>
243 <entry>PostgreSQL 18 and later</entry>
244 <entry>Current latest version. The secret key used in query
245 cancellation was enlarged from 4 bytes to a variable length field. The
246 BackendKeyData message was changed to accommodate that, and the CancelRequest
247 message was redefined to have a variable length payload.
248 </entry>
249 </row>
250 <row>
251 <entry>3.1</entry>
252 <entry>-</entry>
253 <entry>Reserved. Version 3.1 has not been used by any PostgreSQL
254 version, but it was skipped because old versions of the popular
255 pgbouncer application had a bug in the protocol negotiation which made
256 it incorrectly claim that it supported version 3.1.
257 </entry>
258 </row>
259 <row>
260 <entry>3.0</entry>
261 <entry>PostgreSQL 7.4 and later</entry>
262 </row>
263 <row>
264 <entry>2.0</entry>
265 <entry>up to PostgreSQL 13</entry>
266 <entry>See previous releases of
267 the <productname>PostgreSQL</productname> documentation for
268 details</entry>
269 </row>
270 </tbody>
271 </tgroup>
272 </table>
273 </sect2>
274 </sect1>
275
276 <sect1 id="protocol-flow">
277 <title>Message Flow</title>
278
279 <para>
280 This section describes the message flow and the semantics of each
281 message type. (Details of the exact representation of each message
282 appear in <xref linkend="protocol-message-formats"/>.) There are
283 several different sub-protocols depending on the state of the
284 connection: start-up, query, function call,
285 <command>COPY</command>, and termination. There are also special
286 provisions for asynchronous operations (including notification
287 responses and command cancellation), which can occur at any time
288 after the start-up phase.
289 </para>
290
291 <sect2 id="protocol-flow-start-up">
292 <title>Start-up</title>
293
294 <para>
295 To begin a session, a frontend opens a connection to the server and sends
296 a startup message. This message includes the names of the user and of the
297 database the user wants to connect to; it also identifies the particular
298 protocol version to be used. (Optionally, the startup message can include
299 additional settings for run-time parameters.)
300 The server then uses this information and
301 the contents of its configuration files (such as
302 <filename>pg_hba.conf</filename>) to determine
303 whether the connection is provisionally acceptable, and what additional
304 authentication is required (if any).
305 </para>
306
307 <para>
308 The server then sends an appropriate authentication request message,
309 to which the frontend must reply with an appropriate authentication
310 response message (such as a password).
311 For all authentication methods except GSSAPI, SSPI and SASL, there is at
312 most one request and one response. In some methods, no response
313 at all is needed from the frontend, and so no authentication request
314 occurs. For GSSAPI, SSPI and SASL, multiple exchanges of packets may be
315 needed to complete the authentication.
316 </para>
317
318 <para>
319 The authentication cycle ends with the server either rejecting the
320 connection attempt (ErrorResponse), or sending AuthenticationOk.
321 </para>
322
323 <para>
324 The possible messages from the server in this phase are:
325
326 <variablelist>
327 <varlistentry>
328 <term>ErrorResponse</term>
329 <listitem>
330 <para>
331 The connection attempt has been rejected.
332 The server then immediately closes the connection.
333 </para>
334 </listitem>
335 </varlistentry>
336
337 <varlistentry>
338 <term>AuthenticationOk</term>
339 <listitem>
340 <para>
341 The authentication exchange is successfully completed.
342 </para>
343 </listitem>
344 </varlistentry>
345
346 <varlistentry>
347 <term>AuthenticationKerberosV5</term>
348 <listitem>
349 <para>
350 The frontend must now take part in a Kerberos V5
351 authentication dialog (not described here, part of the
352 Kerberos specification) with the server. If this is
353 successful, the server responds with an AuthenticationOk,
354 otherwise it responds with an ErrorResponse. This is no
355 longer supported.
356 </para>
357 </listitem>
358 </varlistentry>
359
360 <varlistentry>
361 <term>AuthenticationCleartextPassword</term>
362 <listitem>
363 <para>
364 The frontend must now send a PasswordMessage containing the
365 password in clear-text form. If
366 this is the correct password, the server responds with an
367 AuthenticationOk, otherwise it responds with an ErrorResponse.
368 </para>
369 </listitem>
370 </varlistentry>
371
372 <varlistentry>
373 <term>AuthenticationMD5Password</term>
374 <listitem>
375 <para>
376 The frontend must now send a PasswordMessage containing the
377 password (with user name) encrypted via MD5, then encrypted
378 again using the 4-byte random salt specified in the
379 AuthenticationMD5Password message. If this is the correct
380 password, the server responds with an AuthenticationOk,
381 otherwise it responds with an ErrorResponse. The actual
382 PasswordMessage can be computed in SQL as <literal>concat('md5',
383 md5(concat(md5(concat(password, username)), random-salt)))</literal>.
384 (Keep in mind the <function>md5()</function> function returns its
385 result as a hex string.)
386 </para>
387 <warning>
388 <para>
389 Support for MD5-encrypted passwords is deprecated and will be removed
390 in a future release of <productname>PostgreSQL</productname>. Refer
391 to <xref linkend="auth-password"/> for details about migrating to
392 another password type.
393 </para>
394 </warning>
395 </listitem>
396 </varlistentry>
397
398 <varlistentry>
399 <term>AuthenticationGSS</term>
400 <listitem>
401 <para>
402 The frontend must now initiate a GSSAPI negotiation. The frontend
403 will send a GSSResponse message with the first part of the GSSAPI
404 data stream in response to this. If further messages are needed,
405 the server will respond with AuthenticationGSSContinue.
406 </para>
407 </listitem>
408 </varlistentry>
409
410 <varlistentry>
411 <term>AuthenticationSSPI</term>
412 <listitem>
413 <para>
414 The frontend must now initiate an SSPI negotiation. The frontend
415 will send a GSSResponse with the first part of the SSPI
416 data stream in response to this. If further messages are needed,
417 the server will respond with AuthenticationGSSContinue.
418 </para>
419 </listitem>
420
421 </varlistentry>
422 <varlistentry>
423 <term>AuthenticationGSSContinue</term>
424 <listitem>
425 <para>
426 This message contains the response data from the previous step
427 of GSSAPI or SSPI negotiation (AuthenticationGSS, AuthenticationSSPI
428 or a previous AuthenticationGSSContinue). If the GSSAPI
429 or SSPI data in this message
430 indicates more data is needed to complete the authentication,
431 the frontend must send that data as another GSSResponse message. If
432 GSSAPI or SSPI authentication is completed by this message, the server
433 will next send AuthenticationOk to indicate successful authentication
434 or ErrorResponse to indicate failure.
435 </para>
436 </listitem>
437 </varlistentry>
438
439 <varlistentry>
440 <term>AuthenticationSASL</term>
441 <listitem>
442 <para>
443 The frontend must now initiate a SASL negotiation, using one of the
444 SASL mechanisms listed in the message. The frontend will send a
445 SASLInitialResponse with the name of the selected mechanism, and the
446 first part of the SASL data stream in response to this. If further
447 messages are needed, the server will respond with
448 AuthenticationSASLContinue. See <xref linkend="sasl-authentication"/>
449 for details.
450 </para>
451 </listitem>
452 </varlistentry>
453
454 <varlistentry>
455 <term>AuthenticationSASLContinue</term>
456 <listitem>
457 <para>
458 This message contains challenge data from the previous step of SASL
459 negotiation (AuthenticationSASL, or a previous
460 AuthenticationSASLContinue). The frontend must respond with a
461 SASLResponse message.
462 </para>
463 </listitem>
464 </varlistentry>
465
466 <varlistentry>
467 <term>AuthenticationSASLFinal</term>
468 <listitem>
469 <para>
470 SASL authentication has completed with additional mechanism-specific
471 data for the client. The server will next send AuthenticationOk to
472 indicate successful authentication, or an ErrorResponse to indicate
473 failure. This message is sent only if the SASL mechanism specifies
474 additional data to be sent from server to client at completion.
475 </para>
476 </listitem>
477 </varlistentry>
478
479 <varlistentry>
480 <term>NegotiateProtocolVersion</term>
481 <listitem>
482 <para>
483 The server does not support the minor protocol version requested
484 by the client, but does support an earlier version of the protocol;
485 this message indicates the highest supported minor version. This
486 message will also be sent if the client requested unsupported protocol
487 options (i.e., beginning with <literal>_pq_.</literal>) in the
488 startup packet.
489 </para>
490 <para>
491 After this message, the authentication will continue using the version
492 indicated by the server. If the client does not support the older
493 version, it should immediately close the connection. If the server
494 does not send this message, it supports the client's requested
495 protocol version and all the protocol options.
496 </para>
497 </listitem>
498 </varlistentry>
499
500 </variablelist>
501 </para>
502
503 <para>
504 If the frontend does not support the authentication method
505 requested by the server, then it should immediately close the
506 connection.
507 </para>
508
509 <para>
510 After having received AuthenticationOk, the frontend must wait
511 for further messages from the server. In this phase a backend process
512 is being started, and the frontend is just an interested bystander.
513 It is still possible for the startup attempt
514 to fail (ErrorResponse) or the server to decline support for the requested
515 minor protocol version (NegotiateProtocolVersion), but in the normal case
516 the backend will send some ParameterStatus messages, BackendKeyData, and
517 finally ReadyForQuery.
518 </para>
519
520 <para>
521 During this phase the backend will attempt to apply any additional
522 run-time parameter settings that were given in the startup message.
523 If successful, these values become session defaults. An error causes
524 ErrorResponse and exit.
525 </para>
526
527 <para>
528 The possible messages from the backend in this phase are:
529
530 <variablelist>
531 <varlistentry>
532 <term>BackendKeyData</term>
533 <listitem>
534 <para>
535 This message provides secret-key data that the frontend must
536 save if it wants to be able to issue cancel requests later.
537 The frontend should not respond to this message, but should
538 continue listening for a ReadyForQuery message.
539 </para>
540 <para>
541 The <productname>PostgreSQL</productname> server will always send this
542 message, but some third party backend implementations of the protocol
543 that don't support query cancellation are known not to.
544 </para>
545 </listitem>
546 </varlistentry>
547
548 <varlistentry>
549 <term>ParameterStatus</term>
550 <listitem>
551 <para>
552 This message informs the frontend about the current (initial)
553 setting of backend parameters, such as <xref
554 linkend="guc-client-encoding"/> or <xref linkend="guc-datestyle"/>.
555 The frontend can ignore this message, or record the settings
556 for its future use; see <xref linkend="protocol-async"/> for
557 more details. The frontend should not respond to this
558 message, but should continue listening for a ReadyForQuery
559 message.
560 </para>
561 </listitem>
562 </varlistentry>
563
564 <varlistentry>
565 <term>ReadyForQuery</term>
566 <listitem>
567 <para>
568 Start-up is completed. The frontend can now issue commands.
569 </para>
570 </listitem>
571 </varlistentry>
572
573 <varlistentry>
574 <term>ErrorResponse</term>
575 <listitem>
576 <para>
577 Start-up failed. The connection is closed after sending this
578 message.
579 </para>
580 </listitem>
581 </varlistentry>
582
583 <varlistentry>
584 <term>NoticeResponse</term>
585 <listitem>
586 <para>
587 A warning message has been issued. The frontend should
588 display the message but continue listening for ReadyForQuery
589 or ErrorResponse.
590 </para>
591 </listitem>
592 </varlistentry>
593 </variablelist>
594 </para>
595
596 <para>
597 The ReadyForQuery message is the same one that the backend will
598 issue after each command cycle. Depending on the coding needs of
599 the frontend, it is reasonable to consider ReadyForQuery as
600 starting a command cycle, or to consider ReadyForQuery as ending the
601 start-up phase and each subsequent command cycle.
602 </para>
603 </sect2>
604
605 <sect2 id="protocol-flow-simple-query">
606 <title>Simple Query</title>
607
608 <para>
609 A simple query cycle is initiated by the frontend sending a Query message
610 to the backend. The message includes an SQL command (or commands)
611 expressed as a text string.
612 The backend then sends one or more response
613 messages depending on the contents of the query command string,
614 and finally a ReadyForQuery response message. ReadyForQuery
615 informs the frontend that it can safely send a new command.
616 (It is not actually necessary for the frontend to wait for
617 ReadyForQuery before issuing another command, but the frontend must
618 then take responsibility for figuring out what happens if the earlier
619 command fails and already-issued later commands succeed.)
620 </para>
621
622 <para>
623 The possible response messages from the backend are:
624
625 <variablelist>
626 <varlistentry>
627 <term>CommandComplete</term>
628 <listitem>
629 <para>
630 An SQL command completed normally.
631 </para>
632 </listitem>
633 </varlistentry>
634
635 <varlistentry>
636 <term>CopyInResponse</term>
637 <listitem>
638 <para>
639 The backend is ready to copy data from the frontend to a
640 table; see <xref linkend="protocol-copy"/>.
641 </para>
642 </listitem>
643 </varlistentry>
644
645 <varlistentry>
646 <term>CopyOutResponse</term>
647 <listitem>
648 <para>
649 The backend is ready to copy data from a table to the
650 frontend; see <xref linkend="protocol-copy"/>.
651 </para>
652 </listitem>
653 </varlistentry>
654
655 <varlistentry>
656 <term>RowDescription</term>
657 <listitem>
658 <para>
659 Indicates that rows are about to be returned in response to
660 a <command>SELECT</command>, <command>FETCH</command>, etc. query.
661 The contents of this message describe the column layout of the rows.
662 This will be followed by a DataRow message for each row being returned
663 to the frontend.
664 </para>
665 </listitem>
666 </varlistentry>
667
668 <varlistentry>
669 <term>DataRow</term>
670 <listitem>
671 <para>
672 One of the set of rows returned by
673 a <command>SELECT</command>, <command>FETCH</command>, etc. query.
674 </para>
675 </listitem>
676 </varlistentry>
677
678 <varlistentry>
679 <term>EmptyQueryResponse</term>
680 <listitem>
681 <para>
682 An empty query string was recognized.
683 </para>
684 </listitem>
685 </varlistentry>
686
687 <varlistentry>
688 <term>ErrorResponse</term>
689 <listitem>
690 <para>
691 An error has occurred.
692 </para>
693 </listitem>
694 </varlistentry>
695
696 <varlistentry>
697 <term>ReadyForQuery</term>
698 <listitem>
699 <para>
700 Processing of the query string is complete. A separate
701 message is sent to indicate this because the query string might
702 contain multiple SQL commands. (CommandComplete marks the
703 end of processing one SQL command, not the whole string.)
704 ReadyForQuery will always be sent, whether processing
705 terminates successfully or with an error.
706 </para>
707 </listitem>
708 </varlistentry>
709
710 <varlistentry>
711 <term>NoticeResponse</term>
712 <listitem>
713 <para>
714 A warning message has been issued in relation to the query.
715 Notices are in addition to other responses, i.e., the backend
716 will continue processing the command.
717 </para>
718 </listitem>
719 </varlistentry>
720
721 </variablelist>
722 </para>
723
724 <para>
725 The response to a <command>SELECT</command> query (or other queries that
726 return row sets, such as <command>EXPLAIN</command> or <command>SHOW</command>)
727 normally consists of RowDescription, zero or more
728 DataRow messages, and then CommandComplete.
729 <command>COPY</command> to or from the frontend invokes special protocol
730 as described in <xref linkend="protocol-copy"/>.
731 All other query types normally produce only
732 a CommandComplete message.
733 </para>
734
735 <para>
736 Since a query string could contain several queries (separated by
737 semicolons), there might be several such response sequences before the
738 backend finishes processing the query string. ReadyForQuery is issued
739 when the entire string has been processed and the backend is ready to
740 accept a new query string.
741 </para>
742
743 <para>
744 If a completely empty (no contents other than whitespace) query string
745 is received, the response is EmptyQueryResponse followed by ReadyForQuery.
746 </para>
747
748 <para>
749 In the event of an error, ErrorResponse is issued followed by
750 ReadyForQuery. All further processing of the query string is aborted by
751 ErrorResponse (even if more queries remained in it). Note that this
752 might occur partway through the sequence of messages generated by an
753 individual query.
754 </para>
755
756 <para>
757 In simple Query mode, the format of retrieved values is always text,
758 except when the given command is a <command>FETCH</command> from a cursor
759 declared with the <literal>BINARY</literal> option. In that case, the
760 retrieved values are in binary format. The format codes given in
761 the RowDescription message tell which format is being used.
762 </para>
763
764 <para>
765 A frontend must be prepared to accept ErrorResponse and
766 NoticeResponse messages whenever it is expecting any other type of
767 message. See also <xref linkend="protocol-async"/> concerning messages
768 that the backend might generate due to outside events.
769 </para>
770
771 <para>
772 Recommended practice is to code frontends in a state-machine style
773 that will accept any message type at any time that it could make sense,
774 rather than wiring in assumptions about the exact sequence of messages.
775 </para>
776
777 <sect3 id="protocol-flow-multi-statement">
778 <title>Multiple Statements in a Simple Query</title>
779
780 <para>
781 When a simple Query message contains more than one SQL statement
782 (separated by semicolons), those statements are executed as a single
783 transaction, unless explicit transaction control commands are included
784 to force a different behavior. For example, if the message contains
785 <programlisting>
786 INSERT INTO mytable VALUES(1);
787 SELECT 1/0;
788 INSERT INTO mytable VALUES(2);
789 </programlisting>
790 then the divide-by-zero failure in the <command>SELECT</command> will force
791 rollback of the first <command>INSERT</command>. Furthermore, because
792 execution of the message is abandoned at the first error, the second
793 <command>INSERT</command> is never attempted at all.
794 </para>
795
796 <para>
797 If instead the message contains
798 <programlisting>
799 BEGIN;
800 INSERT INTO mytable VALUES(1);
801 COMMIT;
802 INSERT INTO mytable VALUES(2);
803 SELECT 1/0;
804 </programlisting>
805 then the first <command>INSERT</command> is committed by the
806 explicit <command>COMMIT</command> command. The second <command>INSERT</command>
807 and the <command>SELECT</command> are still treated as a single transaction,
808 so that the divide-by-zero failure will roll back the
809 second <command>INSERT</command>, but not the first one.
810 </para>
811
812 <para>
813 This behavior is implemented by running the statements in a
814 multi-statement Query message in an <firstterm>implicit transaction
815 block</firstterm> unless there is some explicit transaction block for them to
816 run in. The main difference between an implicit transaction block and
817 a regular one is that an implicit block is closed automatically at the
818 end of the Query message, either by an implicit commit if there was no
819 error, or an implicit rollback if there was an error. This is similar
820 to the implicit commit or rollback that happens for a statement
821 executed by itself (when not in a transaction block).
822 </para>
823
824 <para>
825 If the session is already in a transaction block, as a result of
826 a <command>BEGIN</command> in some previous message, then the Query message
827 simply continues that transaction block, whether the message contains
828 one statement or several. However, if the Query message contains
829 a <command>COMMIT</command> or <command>ROLLBACK</command> closing the existing
830 transaction block, then any following statements are executed in an
831 implicit transaction block.
832 Conversely, if a <command>BEGIN</command> appears in a multi-statement Query
833 message, then it starts a regular transaction block that will only be
834 terminated by an explicit <command>COMMIT</command> or <command>ROLLBACK</command>,
835 whether that appears in this Query message or a later one.
836 If the <command>BEGIN</command> follows some statements that were executed as
837 an implicit transaction block, those statements are not immediately
838 committed; in effect, they are retroactively included into the new
839 regular transaction block.
840 </para>
841
842 <para>
843 A <command>COMMIT</command> or <command>ROLLBACK</command> appearing in an implicit
844 transaction block is executed as normal, closing the implicit block;
845 however, a warning will be issued since a <command>COMMIT</command>
846 or <command>ROLLBACK</command> without a previous <command>BEGIN</command> might
847 represent a mistake. If more statements follow, a new implicit
848 transaction block will be started for them.
849 </para>
850
851 <para>
852 Savepoints are not allowed in an implicit transaction block, since
853 they would conflict with the behavior of automatically closing the
854 block upon any error.
855 </para>
856
857 <para>
858 Remember that, regardless of any transaction control commands that may
859 be present, execution of the Query message stops at the first error.
860 Thus for example given
861 <programlisting>
862 BEGIN;
863 SELECT 1/0;
864 ROLLBACK;
865 </programlisting>
866 in a single Query message, the session will be left inside a failed
867 regular transaction block, since the <command>ROLLBACK</command> is not
868 reached after the divide-by-zero error. Another <command>ROLLBACK</command>
869 will be needed to restore the session to a usable state.
870 </para>
871
872 <para>
873 Another behavior of note is that initial lexical and syntactic
874 analysis is done on the entire query string before any of it is
875 executed. Thus simple errors (such as a misspelled keyword) in later
876 statements can prevent execution of any of the statements. This
877 is normally invisible to users since the statements would all roll
878 back anyway when done as an implicit transaction block. However,
879 it can be visible when attempting to do multiple transactions within a
880 multi-statement Query. For instance, if a typo turned our previous
881 example into
882 <programlisting>
883 BEGIN;
884 INSERT INTO mytable VALUES(1);
885 COMMIT;
886 INSERT INTO mytable VALUES(2);
887 SELCT 1/0;<!-- this typo is intentional -->
888 </programlisting>
889 then none of the statements would get run, resulting in the visible
890 difference that the first <command>INSERT</command> is not committed.
891 Errors detected at semantic analysis or later, such as a misspelled
892 table or column name, do not have this effect.
893 </para>
894
895 <para>
896 Lastly, note that all the statements within the Query message will
897 observe the same value of <function>statement_timestamp()</function>,
898 since that timestamp is updated only upon receipt of the Query
899 message. This will result in them all observing the same
900 value of <function>transaction_timestamp()</function> as well,
901 except in cases where the query string ends a previously-started
902 transaction and begins a new one.
903 </para>
904 </sect3>
905 </sect2>
906
907 <sect2 id="protocol-flow-ext-query">
908 <title>Extended Query</title>
909
910 <para>
911 The extended query protocol breaks down the above-described simple
912 query protocol into multiple steps. The results of preparatory
913 steps can be re-used multiple times for improved efficiency.
914 Furthermore, additional features are available, such as the possibility
915 of supplying data values as separate parameters instead of having to
916 insert them directly into a query string.
917 </para>
918
919 <para>
920 In the extended protocol, the frontend first sends a Parse message,
921 which contains a textual query string, optionally some information
922 about data types of parameter placeholders, and the
923 name of a destination prepared-statement object (an empty string
924 selects the unnamed prepared statement). The response is
925 either ParseComplete or ErrorResponse. Parameter data types can be
926 specified by OID; if not given, the parser attempts to infer the
927 data types in the same way as it would do for untyped literal string
928 constants.
929 </para>
930
931 <note>
932 <para>
933 A parameter data type can be left unspecified by setting it to zero,
934 or by making the array of parameter type OIDs shorter than the
935 number of parameter symbols (<literal>$</literal><replaceable>n</replaceable>)
936 used in the query string. Another special case is that a parameter's
937 type can be specified as <type>void</type> (that is, the OID of the
938 <type>void</type> pseudo-type). This is meant to allow parameter symbols
939 to be used for function parameters that are actually OUT parameters.
940 Ordinarily there is no context in which a <type>void</type> parameter
941 could be used, but if such a parameter symbol appears in a function's
942 parameter list, it is effectively ignored. For example, a function
943 call such as <literal>foo($1,$2,$3,$4)</literal> could match a function with
944 two IN and two OUT arguments, if <literal>$3</literal> and <literal>$4</literal>
945 are specified as having type <type>void</type>.
946 </para>
947 </note>
948
949 <note>
950 <para>
951 The query string contained in a Parse message cannot include more
952 than one SQL statement; else a syntax error is reported. This
953 restriction does not exist in the simple-query protocol, but it
954 does exist in the extended protocol, because allowing prepared
955 statements or portals to contain multiple commands would complicate
956 the protocol unduly.
957 </para>
958 </note>
959
960 <para>
961 If successfully created, a named prepared-statement object lasts till
962 the end of the current session, unless explicitly destroyed. An unnamed
963 prepared statement lasts only until the next Parse statement specifying
964 the unnamed statement as destination is issued. (Note that a simple
965 Query message also destroys the unnamed statement.) Named prepared
966 statements must be explicitly closed before they can be redefined by
967 another Parse message, but this is not required for the unnamed statement.
968 Named prepared statements can also be created and accessed at the SQL
969 command level, using <command>PREPARE</command> and <command>EXECUTE</command>.
970 </para>
971
972 <para>
973 Once a prepared statement exists, it can be readied for execution using a
974 Bind message. The Bind message gives the name of the source prepared
975 statement (empty string denotes the unnamed prepared statement), the name
976 of the destination portal (empty string denotes the unnamed portal), and
977 the values to use for any parameter placeholders present in the prepared
978 statement. The
979 supplied parameter set must match those needed by the prepared statement.
980 (If you declared any <type>void</type> parameters in the Parse message,
981 pass NULL values for them in the Bind message.)
982 Bind also specifies the format to use for any data returned
983 by the query; the format can be specified overall, or per-column.
984 The response is either BindComplete or ErrorResponse.
985 </para>
986
987 <note>
988 <para>
989 The choice between text and binary output is determined by the format
990 codes given in Bind, regardless of the SQL command involved. The
991 <literal>BINARY</literal> attribute in cursor declarations is irrelevant when
992 using extended query protocol.
993 </para>
994 </note>
995
996 <para>
997 Query planning typically occurs when the Bind message is processed.
998 If the prepared statement has no parameters, or is executed repeatedly,
999 the server might save the created plan and re-use it during subsequent
1000 Bind messages for the same prepared statement. However, it will do so
1001 only if it finds that a generic plan can be created that is not much
1002 less efficient than a plan that depends on the specific parameter values
1003 supplied. This happens transparently so far as the protocol is concerned.
1004 </para>
1005
1006 <para>
1007 If successfully created, a named portal object lasts till the end of the
1008 current transaction, unless explicitly destroyed. An unnamed portal is
1009 destroyed at the end of the transaction, or as soon as the next Bind
1010 statement specifying the unnamed portal as destination is issued. (Note
1011 that a simple Query message also destroys the unnamed portal.) Named
1012 portals must be explicitly closed before they can be redefined by another
1013 Bind message, but this is not required for the unnamed portal.
1014 Named portals can also be created and accessed at the SQL
1015 command level, using <command>DECLARE CURSOR</command> and <command>FETCH</command>.
1016 </para>
1017
1018 <para>
1019 Once a portal exists, it can be executed using an Execute message.
1020 The Execute message specifies the portal name (empty string denotes the
1021 unnamed portal) and
1022 a maximum result-row count (zero meaning <quote>fetch all rows</quote>).
1023 The result-row count is only meaningful for portals
1024 containing commands that return row sets; in other cases the command is
1025 always executed to completion, and the row count is ignored.
1026 The possible
1027 responses to Execute are the same as those described above for queries
1028 issued via simple query protocol, except that Execute doesn't cause
1029 ReadyForQuery or RowDescription to be issued.
1030 </para>
1031
1032 <para>
1033 If Execute terminates before completing the execution of a portal
1034 (due to reaching a nonzero result-row count), it will send a
1035 PortalSuspended message; the appearance of this message tells the frontend
1036 that another Execute should be issued against the same portal to
1037 complete the operation. The CommandComplete message indicating
1038 completion of the source SQL command is not sent until
1039 the portal's execution is completed. Therefore, an Execute phase is
1040 always terminated by the appearance of exactly one of these messages:
1041 CommandComplete, EmptyQueryResponse (if the portal was created from
1042 an empty query string), ErrorResponse, or PortalSuspended.
1043 </para>
1044
1045 <para>
1046 At completion of each series of extended-query messages, the frontend
1047 should issue a Sync message. This parameterless message causes the
1048 backend to close the current transaction if it's not inside a
1049 <command>BEGIN</command>/<command>COMMIT</command> transaction block (<quote>close</quote>
1050 meaning to commit if no error, or roll back if error). Then a
1051 ReadyForQuery response is issued. The purpose of Sync is to provide
1052 a resynchronization point for error recovery. When an error is detected
1053 while processing any extended-query message, the backend issues
1054 ErrorResponse, then reads and discards messages until a Sync is reached,
1055 then issues ReadyForQuery and returns to normal message processing.
1056 (But note that no skipping occurs if an error is detected
1057 <emphasis>while</emphasis> processing Sync &mdash; this ensures that there is one
1058 and only one ReadyForQuery sent for each Sync.)
1059 </para>
1060
1061 <note>
1062 <para>
1063 Sync does not cause a transaction block opened with <command>BEGIN</command>
1064 to be closed. It is possible to detect this situation since the
1065 ReadyForQuery message includes transaction status information.
1066 </para>
1067 </note>
1068
1069 <para>
1070 In addition to these fundamental, required operations, there are several
1071 optional operations that can be used with extended-query protocol.
1072 </para>
1073
1074 <para>
1075 The Describe message (portal variant) specifies the name of an existing
1076 portal (or an empty string for the unnamed portal). The response is a
1077 RowDescription message describing the rows that will be returned by
1078 executing the portal; or a NoData message if the portal does not contain a
1079 query that will return rows; or ErrorResponse if there is no such portal.
1080 </para>
1081
1082 <para>
1083 The Describe message (statement variant) specifies the name of an existing
1084 prepared statement (or an empty string for the unnamed prepared
1085 statement). The response is a ParameterDescription message describing the
1086 parameters needed by the statement, followed by a RowDescription message
1087 describing the rows that will be returned when the statement is eventually
1088 executed (or a NoData message if the statement will not return rows).
1089 ErrorResponse is issued if there is no such prepared statement. Note that
1090 since Bind has not yet been issued, the formats to be used for returned
1091 columns are not yet known to the backend; the format code fields in the
1092 RowDescription message will be zeroes in this case.
1093 </para>
1094
1095 <tip>
1096 <para>
1097 In most scenarios the frontend should issue one or the other variant
1098 of Describe before issuing Execute, to ensure that it knows how to
1099 interpret the results it will get back.
1100 </para>
1101 </tip>
1102
1103 <para>
1104 The Close message closes an existing prepared statement or portal
1105 and releases resources. It is not an error to issue Close against
1106 a nonexistent statement or portal name. The response is normally
1107 CloseComplete, but could be ErrorResponse if some difficulty is
1108 encountered while releasing resources. Note that closing a prepared
1109 statement implicitly closes any open portals that were constructed
1110 from that statement.
1111 </para>
1112
1113 <para>
1114 The Flush message does not cause any specific output to be generated,
1115 but forces the backend to deliver any data pending in its output
1116 buffers. A Flush must be sent after any extended-query command except
1117 Sync, if the frontend wishes to examine the results of that command before
1118 issuing more commands. Without Flush, messages returned by the backend
1119 will be combined into the minimum possible number of packets to minimize
1120 network overhead.
1121 </para>
1122
1123 <note>
1124 <para>
1125 The simple Query message is approximately equivalent to the series Parse,
1126 Bind, portal Describe, Execute, Close, Sync, using the unnamed prepared
1127 statement and portal objects and no parameters. One difference is that
1128 it will accept multiple SQL statements in the query string, automatically
1129 performing the bind/describe/execute sequence for each one in succession.
1130 Another difference is that it will not return ParseComplete, BindComplete,
1131 CloseComplete, or NoData messages.
1132 </para>
1133 </note>
1134 </sect2>
1135
1136 <sect2 id="protocol-flow-pipelining">
1137 <title>Pipelining</title>
1138
1139 <indexterm zone="protocol-flow-pipelining">
1140 <primary>pipelining</primary>
1141 <secondary>protocol specification</secondary>
1142 </indexterm>
1143
1144 <para>
1145 Use of the extended query protocol
1146 allows <firstterm>pipelining</firstterm>, which means sending a series
1147 of queries without waiting for earlier ones to complete. This reduces
1148 the number of network round trips needed to complete a given series of
1149 operations. However, the user must carefully consider the required
1150 behavior if one of the steps fails, since later queries will already
1151 be in flight to the server.
1152 </para>
1153
1154 <para>
1155 One way to deal with that is to make the whole query series be a
1156 single transaction, that is wrap it in <command>BEGIN</command> ...
1157 <command>COMMIT</command>. However, this does not help if one wishes
1158 for some of the commands to commit independently of others.
1159 </para>
1160
1161 <para>
1162 The extended query protocol provides another way to manage this
1163 concern, which is to omit sending Sync messages between steps that
1164 are dependent. Since, after an error, the backend will skip command
1165 messages until it finds Sync, this allows later commands in a pipeline
1166 to be skipped automatically when an earlier one fails, without the
1167 client having to manage that explicitly with <command>BEGIN</command>
1168 and <command>COMMIT</command>. Independently-committable segments
1169 of the pipeline can be separated by Sync messages.
1170 </para>
1171
1172 <para>
1173 If the client has not issued an explicit <command>BEGIN</command>,
1174 then an implicit transaction block is started and each Sync ordinarily
1175 causes an implicit <command>COMMIT</command> if the preceding step(s)
1176 succeeded, or an implicit <command>ROLLBACK</command> if they failed.
1177 This implicit transaction block will only be detected by the server
1178 when the first command ends without a sync. There are a few DDL
1179 commands (such as <command>CREATE DATABASE</command>) that cannot be
1180 executed inside a transaction block. If one of these is executed in a
1181 pipeline, it will fail unless it is the first command after a Sync.
1182 Furthermore, upon success it will force an immediate commit to preserve
1183 database consistency. Thus a Sync immediately following one of these
1184 commands has no effect except to respond with ReadyForQuery.
1185 </para>
1186
1187 <para>
1188 When using this method, completion of the pipeline must be determined
1189 by counting ReadyForQuery messages and waiting for that to reach the
1190 number of Syncs sent. Counting command completion responses is
1191 unreliable, since some of the commands may be skipped and thus not
1192 produce a completion message.
1193 </para>
1194 </sect2>
1195
1196 <sect2 id="protocol-flow-function-call">
1197 <title>Function Call</title>
1198
1199 <para>
1200 The Function Call sub-protocol allows the client to request a direct
1201 call of any function that exists in the database's
1202 <structname>pg_proc</structname> system catalog. The client must have
1203 execute permission for the function.
1204 </para>
1205
1206 <note>
1207 <para>
1208 The Function Call sub-protocol is a legacy feature that is probably best
1209 avoided in new code. Similar results can be accomplished by setting up
1210 a prepared statement that does <literal>SELECT function($1, ...)</literal>.
1211 The Function Call cycle can then be replaced with Bind/Execute.
1212 </para>
1213 </note>
1214
1215 <para>
1216 A Function Call cycle is initiated by the frontend sending a
1217 FunctionCall message to the backend. The backend then sends one
1218 or more response messages depending on the results of the function
1219 call, and finally a ReadyForQuery response message. ReadyForQuery
1220 informs the frontend that it can safely send a new query or
1221 function call.
1222 </para>
1223
1224 <para>
1225 The possible response messages from the backend are:
1226
1227 <variablelist>
1228 <varlistentry>
1229 <term>ErrorResponse</term>
1230 <listitem>
1231 <para>
1232 An error has occurred.
1233 </para>
1234 </listitem>
1235 </varlistentry>
1236
1237 <varlistentry>
1238 <term>FunctionCallResponse</term>
1239 <listitem>
1240 <para>
1241 The function call was completed and returned the result given
1242 in the message.
1243 (Note that the Function Call protocol can only handle a single
1244 scalar result, not a row type or set of results.)
1245 </para>
1246 </listitem>
1247 </varlistentry>
1248
1249 <varlistentry>
1250 <term>ReadyForQuery</term>
1251 <listitem>
1252 <para>
1253 Processing of the function call is complete. ReadyForQuery
1254 will always be sent, whether processing terminates
1255 successfully or with an error.
1256 </para>
1257 </listitem>
1258 </varlistentry>
1259
1260 <varlistentry>
1261 <term>NoticeResponse</term>
1262 <listitem>
1263 <para>
1264 A warning message has been issued in relation to the function
1265 call. Notices are in addition to other responses, i.e., the
1266 backend will continue processing the command.
1267 </para>
1268 </listitem>
1269 </varlistentry>
1270 </variablelist>
1271 </para>
1272 </sect2>
1273
1274 <sect2 id="protocol-copy">
1275 <title>COPY Operations</title>
1276
1277 <para>
1278 The <command>COPY</command> command allows high-speed bulk data transfer
1279 to or from the server. Copy-in and copy-out operations each switch
1280 the connection into a distinct sub-protocol, which lasts until the
1281 operation is completed.
1282 </para>
1283
1284 <para>
1285 Copy-in mode (data transfer to the server) is initiated when the
1286 backend executes a <command>COPY FROM STDIN</command> SQL statement. The backend
1287 sends a CopyInResponse message to the frontend. The frontend should
1288 then send zero or more CopyData messages, forming a stream of input
1289 data. (The message boundaries are not required to have anything to do
1290 with row boundaries, although that is often a reasonable choice.)
1291 The frontend can terminate the copy-in mode by sending either a CopyDone
1292 message (allowing successful termination) or a CopyFail message (which
1293 will cause the <command>COPY</command> SQL statement to fail with an
1294 error). The backend then reverts to the command-processing mode it was
1295 in before the <command>COPY</command> started, which will be either simple or
1296 extended query protocol. It will next send either CommandComplete
1297 (if successful) or ErrorResponse (if not).
1298 </para>
1299
1300 <para>
1301 In the event of a backend-detected error during copy-in mode (including
1302 receipt of a CopyFail message), the backend will issue an ErrorResponse
1303 message. If the <command>COPY</command> command was issued via an extended-query
1304 message, the backend will now discard frontend messages until a Sync
1305 message is received, then it will issue ReadyForQuery and return to normal
1306 processing. If the <command>COPY</command> command was issued in a simple
1307 Query message, the rest of that message is discarded and ReadyForQuery
1308 is issued. In either case, any subsequent CopyData, CopyDone, or CopyFail
1309 messages issued by the frontend will simply be dropped.
1310 </para>
1311
1312 <para>
1313 The backend will ignore Flush and Sync messages received during copy-in
1314 mode. Receipt of any other non-copy message type constitutes an error
1315 that will abort the copy-in state as described above. (The exception for
1316 Flush and Sync is for the convenience of client libraries that always
1317 send Flush or Sync after an Execute message, without checking whether
1318 the command to be executed is a <command>COPY FROM STDIN</command>.)
1319 </para>
1320
1321 <para>
1322 Copy-out mode (data transfer from the server) is initiated when the
1323 backend executes a <command>COPY TO STDOUT</command> SQL statement. The backend
1324 sends a CopyOutResponse message to the frontend, followed by
1325 zero or more CopyData messages (always one per row), followed by CopyDone.
1326 The backend then reverts to the command-processing mode it was
1327 in before the <command>COPY</command> started, and sends CommandComplete.
1328 The frontend cannot abort the transfer (except by closing the connection
1329 or issuing a Cancel request),
1330 but it can discard unwanted CopyData and CopyDone messages.
1331 </para>
1332
1333 <para>
1334 In the event of a backend-detected error during copy-out mode,
1335 the backend will issue an ErrorResponse message and revert to normal
1336 processing. The frontend should treat receipt of ErrorResponse as
1337 terminating the copy-out mode.
1338 </para>
1339
1340 <para>
1341 It is possible for NoticeResponse and ParameterStatus messages to be
1342 interspersed between CopyData messages; frontends must handle these cases,
1343 and should be prepared for other asynchronous message types as well (see
1344 <xref linkend="protocol-async"/>). Otherwise, any message type other than
1345 CopyData or CopyDone may be treated as terminating copy-out mode.
1346 </para>
1347
1348 <para>
1349 There is another Copy-related mode called copy-both, which allows
1350 high-speed bulk data transfer to <emphasis>and</emphasis> from the server.
1351 Copy-both mode is initiated when a backend in walsender mode
1352 executes a <command>START_REPLICATION</command> statement. The
1353 backend sends a CopyBothResponse message to the frontend. Both
1354 the backend and the frontend may then send CopyData messages
1355 until either end sends a CopyDone message. After the client
1356 sends a CopyDone message, the connection goes from copy-both mode to
1357 copy-out mode, and the client may not send any more CopyData messages.
1358 Similarly, when the server sends a CopyDone message, the connection
1359 goes into copy-in mode, and the server may not send any more CopyData
1360 messages. After both sides have sent a CopyDone message, the copy mode
1361 is terminated, and the backend reverts to the command-processing mode.
1362 In the event of a backend-detected error during copy-both mode,
1363 the backend will issue an ErrorResponse message, discard frontend messages
1364 until a Sync message is received, and then issue ReadyForQuery and return
1365 to normal processing. The frontend should treat receipt of ErrorResponse
1366 as terminating the copy in both directions; no CopyDone should be sent
1367 in this case. See <xref linkend="protocol-replication"/> for more
1368 information on the subprotocol transmitted over copy-both mode.
1369 </para>
1370
1371 <para>
1372 The CopyInResponse, CopyOutResponse and CopyBothResponse messages
1373 include fields that inform the frontend of the number of columns
1374 per row and the format codes being used for each column. (As of
1375 the present implementation, all columns in a given <command>COPY</command>
1376 operation will use the same format, but the message design does not
1377 assume this.)
1378 </para>
1379
1380 </sect2>
1381
1382 <sect2 id="protocol-async">
1383 <title>Asynchronous Operations</title>
1384
1385 <para>
1386 There are several cases in which the backend will send messages that
1387 are not specifically prompted by the frontend's command stream.
1388 Frontends must be prepared to deal with these messages at any time,
1389 even when not engaged in a query.
1390 At minimum, one should check for these cases before beginning to
1391 read a query response.
1392 </para>
1393
1394 <para>
1395 It is possible for NoticeResponse messages to be generated due to
1396 outside activity; for example, if the database administrator commands
1397 a <quote>fast</quote> database shutdown, the backend will send a NoticeResponse
1398 indicating this fact before closing the connection. Accordingly,
1399 frontends should always be prepared to accept and display NoticeResponse
1400 messages, even when the connection is nominally idle.
1401 </para>
1402
1403 <para>
1404 ParameterStatus messages will be generated whenever the active
1405 value changes for any of the parameters the backend believes the
1406 frontend should know about. Most commonly this occurs in response
1407 to a <command>SET</command> SQL command executed by the frontend, and
1408 this case is effectively synchronous &mdash; but it is also possible
1409 for parameter status changes to occur because the administrator
1410 changed a configuration file and then sent the
1411 <systemitem>SIGHUP</systemitem> signal to the server. Also,
1412 if a <command>SET</command> command is rolled back, an appropriate
1413 ParameterStatus message will be generated to report the current
1414 effective value.
1415 </para>
1416
1417 <para>
1418 At present there is a hard-wired set of parameters for which
1419 ParameterStatus will be generated. They are:
1420 <simplelist type="vert" columns="2">
1421 <member><varname>application_name</varname></member>
1422 <member><varname>client_encoding</varname></member>
1423 <member><varname>DateStyle</varname></member>
1424 <member><varname>default_transaction_read_only</varname></member>
1425 <member><varname>in_hot_standby</varname></member>
1426 <member><varname>integer_datetimes</varname></member>
1427 <member><varname>IntervalStyle</varname></member>
1428 <member><varname>is_superuser</varname></member>
1429 <member><varname>scram_iterations</varname></member>
1430 <member><varname>search_path</varname></member>
1431 <member><varname>server_encoding</varname></member>
1432 <member><varname>server_version</varname></member>
1433 <member><varname>session_authorization</varname></member>
1434 <member><varname>standard_conforming_strings</varname></member>
1435 <member><varname>TimeZone</varname></member>
1436 </simplelist>
1437 (<varname>default_transaction_read_only</varname> and
1438 <varname>in_hot_standby</varname> were not reported by releases before
1439 14; <varname>scram_iterations</varname> was not reported by releases
1440 before 16; <varname>search_path</varname> was not reported by releases
1441 before 18.)
1442 Note that
1443 <varname>server_version</varname>,
1444 <varname>server_encoding</varname> and
1445 <varname>integer_datetimes</varname>
1446 are pseudo-parameters that cannot change after startup.
1447 This set might change in the future, or even become configurable.
1448 Accordingly, a frontend should simply ignore ParameterStatus for
1449 parameters that it does not understand or care about.
1450 </para>
1451
1452 <para>
1453 If a frontend issues a <command>LISTEN</command> command, then the
1454 backend will send a NotificationResponse message (not to be
1455 confused with NoticeResponse!) whenever a
1456 <command>NOTIFY</command> command is executed for the same
1457 channel name.
1458 </para>
1459
1460 <note>
1461 <para>
1462 At present, NotificationResponse can only be sent outside a
1463 transaction, and thus it will not occur in the middle of a
1464 command-response series, though it might occur just before ReadyForQuery.
1465 It is unwise to design frontend logic that assumes that, however.
1466 Good practice is to be able to accept NotificationResponse at any
1467 point in the protocol.
1468 </para>
1469 </note>
1470 </sect2>
1471
1472 <sect2 id="protocol-flow-canceling-requests">
1473 <title>Canceling Requests in Progress</title>
1474
1475 <para>
1476 During the processing of a query, the frontend might request
1477 cancellation of the query. The cancel request is not sent
1478 directly on the open connection to the backend for reasons of
1479 implementation efficiency: we don't want to have the backend
1480 constantly checking for new input from the frontend during query
1481 processing. Cancel requests should be relatively infrequent, so
1482 we make them slightly cumbersome in order to avoid a penalty in
1483 the normal case.
1484 </para>
1485
1486 <para>
1487 To issue a cancel request, the frontend opens a new connection to
1488 the server and sends a CancelRequest message, rather than the
1489 StartupMessage message that would ordinarily be sent across a new
1490 connection. The server will process this request and then close
1491 the connection. For security reasons, no direct reply is made to
1492 the cancel request message.
1493 </para>
1494
1495 <para>
1496 A CancelRequest message will be ignored unless it contains the
1497 same key data (PID and secret key) passed to the frontend during
1498 connection start-up. If the request matches the PID and secret
1499 key for a currently executing backend, the processing of the
1500 current query is aborted. (In the existing implementation, this is
1501 done by sending a special signal to the backend process that is
1502 processing the query.)
1503 </para>
1504
1505 <para>
1506 The cancellation signal might or might not have any effect &mdash; for
1507 example, if it arrives after the backend has finished processing
1508 the query, then it will have no effect. If the cancellation is
1509 effective, it results in the current command being terminated
1510 early with an error message.
1511 </para>
1512
1513 <para>
1514 The upshot of all this is that for reasons of both security and
1515 efficiency, the frontend has no direct way to tell whether a
1516 cancel request has succeeded. It must continue to wait for the
1517 backend to respond to the query. Issuing a cancel simply improves
1518 the odds that the current query will finish soon, and improves the
1519 odds that it will fail with an error message instead of
1520 succeeding.
1521 </para>
1522
1523 <para>
1524 Since the cancel request is sent across a new connection to the
1525 server and not across the regular frontend/backend communication
1526 link, it is possible for the cancel request to be issued by any
1527 process, not just the frontend whose query is to be canceled.
1528 This might provide additional flexibility when building
1529 multiple-process applications. It also introduces a security
1530 risk, in that unauthorized persons might try to cancel queries.
1531 The security risk is addressed by requiring a dynamically
1532 generated secret key to be supplied in cancel requests.
1533 </para>
1534 </sect2>
1535
1536 <sect2 id="protocol-flow-termination">
1537 <title>Termination</title>
1538
1539 <para>
1540 The normal, graceful termination procedure is that the frontend
1541 sends a Terminate message and immediately closes the connection.
1542 On receipt of this message, the backend closes the connection and
1543 terminates.
1544 </para>
1545
1546 <para>
1547 In rare cases (such as an administrator-commanded database shutdown)
1548 the backend might disconnect without any frontend request to do so.
1549 In such cases the backend will attempt to send an error or notice message
1550 giving the reason for the disconnection before it closes the connection.
1551 </para>
1552
1553 <para>
1554 Other termination scenarios arise from various failure cases, such as core
1555 dump at one end or the other, loss of the communications link, loss of
1556 message-boundary synchronization, etc. If either frontend or backend sees
1557 an unexpected closure of the connection, it should clean
1558 up and terminate. The frontend has the option of launching a new backend
1559 by recontacting the server if it doesn't want to terminate itself.
1560 Closing the connection is also advisable if an unrecognizable message type
1561 is received, since this probably indicates loss of message-boundary sync.
1562 </para>
1563
1564 <para>
1565 For either normal or abnormal termination, any open transaction is
1566 rolled back, not committed. One should note however that if a
1567 frontend disconnects while a non-<command>SELECT</command> query
1568 is being processed, the backend will probably finish the query
1569 before noticing the disconnection. If the query is outside any
1570 transaction block (<command>BEGIN</command> ... <command>COMMIT</command>
1571 sequence) then its results might be committed before the
1572 disconnection is recognized.
1573 </para>
1574 </sect2>
1575
1576 <sect2 id="protocol-flow-ssl">
1577 <title><acronym>SSL</acronym> Session Encryption</title>
1578
1579 <para>
1580 If <productname>PostgreSQL</productname> was built with
1581 <acronym>SSL</acronym> support, frontend/backend communications
1582 can be encrypted using <acronym>SSL</acronym>. This provides
1583 communication security in environments where attackers might be
1584 able to capture the session traffic. For more information on
1585 encrypting <productname>PostgreSQL</productname> sessions with
1586 <acronym>SSL</acronym>, see <xref linkend="ssl-tcp"/>.
1587 </para>
1588
1589 <para>
1590 To initiate an <acronym>SSL</acronym>-encrypted connection, the
1591 frontend initially sends an SSLRequest message rather than a
1592 StartupMessage. The server then responds with a single byte
1593 containing <literal>S</literal> or <literal>N</literal>, indicating that it is
1594 willing or unwilling to perform <acronym>SSL</acronym>,
1595 respectively. The frontend might close the connection at this point
1596 if it is dissatisfied with the response. To continue after
1597 <literal>S</literal>, perform an <acronym>SSL</acronym> startup handshake
1598 (not described here, part of the <acronym>SSL</acronym>
1599 specification) with the server. If this is successful, continue
1600 with sending the usual StartupMessage. In this case the
1601 StartupMessage and all subsequent data will be
1602 <acronym>SSL</acronym>-encrypted. To continue after
1603 <literal>N</literal>, send the usual StartupMessage and proceed without
1604 encryption.
1605 (Alternatively, it is permissible to issue a GSSENCRequest message
1606 after an <literal>N</literal> response to try to
1607 use <acronym>GSSAPI</acronym> encryption instead
1608 of <acronym>SSL</acronym>.)
1609 </para>
1610
1611 <para>
1612 The frontend should also be prepared to handle an ErrorMessage
1613 response to SSLRequest from the server. The frontend should not display
1614 this error message to the user/application, since the server has not been
1615 authenticated
1616 (<ulink url="https://www.postgresql.org/support/security/CVE-2024-10977/">CVE-2024-10977</ulink>).
1617 In this case the connection must
1618 be closed, but the frontend might choose to open a fresh connection
1619 and proceed without requesting <acronym>SSL</acronym>.
1620 </para>
1621
1622 <para>
1623 When <acronym>SSL</acronym> encryption can be performed, the server
1624 is expected to send only the single <literal>S</literal> byte and then
1625 wait for the frontend to initiate an <acronym>SSL</acronym> handshake.
1626 If additional bytes are available to read at this point, it likely
1627 means that a man-in-the-middle is attempting to perform a
1628 buffer-stuffing attack
1629 (<ulink url="https://www.postgresql.org/support/security/CVE-2021-23222/">CVE-2021-23222</ulink>).
1630 Frontends should be coded either to read exactly one byte from the
1631 socket before turning the socket over to their SSL library, or to
1632 treat it as a protocol violation if they find they have read additional
1633 bytes.
1634 </para>
1635
1636 <para>
1637 Likewise the server expects the client to not begin
1638 the <acronym>SSL</acronym> negotiation until it receives the server's
1639 single byte response to the <acronym>SSL</acronym> request. If the
1640 client begins the <acronym>SSL</acronym> negotiation immediately without
1641 waiting for the server response to be received it can reduce connection
1642 latency by one round-trip. However this comes at the cost of not being
1643 able to handle the case where the server sends a negative response to the
1644 <acronym>SSL</acronym> request. In that case instead of continuing with either GSSAPI or an
1645 unencrypted connection or a protocol error the server will simply
1646 disconnect.
1647 </para>
1648
1649 <para>
1650 An initial SSLRequest can also be used in a connection that is being
1651 opened to send a CancelRequest message.
1652 </para>
1653
1654 <para>
1655 A second alternate way to initiate <acronym>SSL</acronym> encryption is
1656 available. The server will recognize connections which immediately
1657 begin <acronym>SSL</acronym> negotiation without any previous SSLRequest
1658 packets. Once the <acronym>SSL</acronym> connection is established the
1659 server will expect a normal startup-request packet and continue
1660 negotiation over the encrypted channel. In this case any other requests
1661 for encryption will be refused. This method is not preferred for general
1662 purpose tools as it cannot negotiate the best connection encryption
1663 available or handle unencrypted connections. However it is useful for
1664 environments where both the server and client are controlled together.
1665 In that case it avoids one round trip of latency and allows the use of
1666 network tools that depend on standard <acronym>SSL</acronym> connections.
1667 When using <acronym>SSL</acronym> connections in this style the client is
1668 required to use the ALPN extension defined
1669 by <ulink url="https://tools.ietf.org/html/rfc7301">RFC 7301</ulink> to
1670 protect against protocol confusion attacks.
1671 The <productname>PostgreSQL</productname> protocol is "postgresql" as
1672 registered
1673 at <ulink url="https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids">IANA
1674 TLS ALPN Protocol IDs</ulink> registry.
1675 </para>
1676
1677 <para>
1678 While the protocol itself does not provide a way for the server to
1679 force <acronym>SSL</acronym> encryption, the administrator can
1680 configure the server to reject unencrypted sessions as a byproduct
1681 of authentication checking.
1682 </para>
1683 </sect2>
1684
1685 <sect2 id="protocol-flow-gssapi">
1686 <title><acronym>GSSAPI</acronym> Session Encryption</title>
1687
1688 <para>
1689 If <productname>PostgreSQL</productname> was built with
1690 <acronym>GSSAPI</acronym> support, frontend/backend communications
1691 can be encrypted using <acronym>GSSAPI</acronym>. This provides
1692 communication security in environments where attackers might be
1693 able to capture the session traffic. For more information on
1694 encrypting <productname>PostgreSQL</productname> sessions with
1695 <acronym>GSSAPI</acronym>, see <xref linkend="gssapi-enc"/>.
1696 </para>
1697
1698 <para>
1699 To initiate a <acronym>GSSAPI</acronym>-encrypted connection, the
1700 frontend initially sends a GSSENCRequest message rather than a
1701 StartupMessage. The server then responds with a single byte
1702 containing <literal>G</literal> or <literal>N</literal>, indicating that it
1703 is willing or unwilling to perform <acronym>GSSAPI</acronym> encryption,
1704 respectively. The frontend might close the connection at this point
1705 if it is dissatisfied with the response. To continue after
1706 <literal>G</literal>, using the GSSAPI C bindings as discussed in
1707 <ulink url="https://datatracker.ietf.org/doc/html/rfc2744">RFC 2744</ulink>
1708 or equivalent, perform a <acronym>GSSAPI</acronym> initialization by
1709 calling <function>gss_init_sec_context()</function> in a loop and sending
1710 the result to the server, starting with an empty input and then with each
1711 result from the server, until it returns no output. When sending the
1712 results of <function>gss_init_sec_context()</function> to the server,
1713 prepend the length of the message as a four byte integer in network byte
1714 order.
1715 To continue after
1716 <literal>N</literal>, send the usual StartupMessage and proceed without
1717 encryption.
1718 (Alternatively, it is permissible to issue an SSLRequest message
1719 after an <literal>N</literal> response to try to
1720 use <acronym>SSL</acronym> encryption instead
1721 of <acronym>GSSAPI</acronym>.)
1722 </para>
1723
1724 <para>
1725 The frontend should also be prepared to handle an ErrorMessage
1726 response to GSSENCRequest from the server. The frontend should not display
1727 this error message to the user/application, since the server has not been
1728 authenticated
1729 (<ulink url="https://www.postgresql.org/support/security/CVE-2024-10977/">CVE-2024-10977</ulink>).
1730 In this case the connection must be closed, but the frontend might choose
1731 to open a fresh connection and proceed without requesting
1732 <acronym>GSSAPI</acronym> encryption.
1733 </para>
1734
1735 <para>
1736 When <acronym>GSSAPI</acronym> encryption can be performed, the server
1737 is expected to send only the single <literal>G</literal> byte and then
1738 wait for the frontend to initiate a <acronym>GSSAPI</acronym> handshake.
1739 If additional bytes are available to read at this point, it likely
1740 means that a man-in-the-middle is attempting to perform a
1741 buffer-stuffing attack
1742 (<ulink url="https://www.postgresql.org/support/security/CVE-2021-23222/">CVE-2021-23222</ulink>).
1743 Frontends should be coded either to read exactly one byte from the
1744 socket before turning the socket over to their GSSAPI library, or to
1745 treat it as a protocol violation if they find they have read additional
1746 bytes.
1747 </para>
1748
1749 <para>
1750 An initial GSSENCRequest can also be used in a connection that is being
1751 opened to send a CancelRequest message.
1752 </para>
1753
1754 <para>
1755 Once <acronym>GSSAPI</acronym> encryption has been successfully
1756 established, use <function>gss_wrap()</function> to
1757 encrypt the usual StartupMessage and all subsequent data, prepending the
1758 length of the result from <function>gss_wrap()</function> as a four byte
1759 integer in network byte order to the actual encrypted payload. Note that
1760 the server will only accept encrypted packets from the client which are less
1761 than 16kB; <function>gss_wrap_size_limit()</function> should be used by the
1762 client to determine the size of the unencrypted message which will fit
1763 within this limit and larger messages should be broken up into multiple
1764 <function>gss_wrap()</function> calls. Typical segments are 8kB of
1765 unencrypted data, resulting in encrypted packets of slightly larger than 8kB
1766 but well within the 16kB maximum. The server can be expected to not send
1767 encrypted packets of larger than 16kB to the client.
1768 </para>
1769
1770 <para>
1771 While the protocol itself does not provide a way for the server to
1772 force <acronym>GSSAPI</acronym> encryption, the administrator can
1773 configure the server to reject unencrypted sessions as a byproduct
1774 of authentication checking.
1775 </para>
1776 </sect2>
1777 </sect1>
1778
1779 <sect1 id="sasl-authentication">
1780 <title>SASL Authentication</title>
1781
1782 <para>
1783 <firstterm>SASL</firstterm> is a framework for authentication in connection-oriented
1784 protocols. At the moment, <productname>PostgreSQL</productname> implements three
1785 SASL authentication mechanisms: SCRAM-SHA-256, SCRAM-SHA-256-PLUS, and
1786 OAUTHBEARER. More might be added in the future. The below steps illustrate how SASL
1787 authentication is performed in general, while the next subsections give
1788 more details on particular mechanisms.
1789 </para>
1790
1791 <procedure>
1792 <title>SASL Authentication Message Flow</title>
1793
1794 <step id="sasl-auth-begin">
1795 <para>
1796 To begin a SASL authentication exchange, the server sends an
1797 AuthenticationSASL message. It includes a list of SASL authentication
1798 mechanisms that the server can accept, in the server's preferred order.
1799 </para>
1800 </step>
1801
1802 <step id="sasl-auth-initial-response">
1803 <para>
1804 The client selects one of the supported mechanisms from the list, and sends
1805 a SASLInitialResponse message to the server. The message includes the name
1806 of the selected mechanism, and an optional Initial Client Response, if the
1807 selected mechanism uses that.
1808 </para>
1809 </step>
1810
1811 <step id="sasl-auth-continue">
1812 <para>
1813 One or more server-challenge and client-response message will follow. Each
1814 server-challenge is sent in an AuthenticationSASLContinue message, followed
1815 by a response from client in a SASLResponse message. The particulars of
1816 the messages are mechanism specific.
1817 </para>
1818 </step>
1819
1820 <step id="sasl-auth-end">
1821 <para>
1822 Finally, when the authentication exchange is completed successfully, the
1823 server sends an optional AuthenticationSASLFinal message, followed
1824 immediately by an AuthenticationOk message. The AuthenticationSASLFinal
1825 contains additional server-to-client data, whose content is particular to the
1826 selected authentication mechanism. If the authentication mechanism doesn't
1827 use additional data that's sent at completion, the AuthenticationSASLFinal
1828 message is not sent.
1829 </para>
1830 </step>
1831 </procedure>
1832
1833 <para>
1834 On error, the server can abort the authentication at any stage, and send an
1835 ErrorMessage.
1836 </para>
1837
1838 <sect2 id="sasl-scram-sha-256">
1839 <title>SCRAM-SHA-256 Authentication</title>
1840
1841 <para>
1842 <literal>SCRAM-SHA-256</literal>, and its variant with channel
1843 binding <literal>SCRAM-SHA-256-PLUS</literal>, are password-based
1844 authentication mechanisms. They are described in
1845 detail in <ulink url="https://datatracker.ietf.org/doc/html/rfc7677">RFC 7677</ulink>
1846 and <ulink url="https://datatracker.ietf.org/doc/html/rfc5802">RFC 5802</ulink>.
1847 </para>
1848
1849 <para>
1850 When SCRAM-SHA-256 is used in PostgreSQL, the server will ignore the user name
1851 that the client sends in the <structname>client-first-message</structname>. The user name
1852 that was already sent in the startup message is used instead.
1853 <productname>PostgreSQL</productname> supports multiple character encodings, while SCRAM
1854 dictates UTF-8 to be used for the user name, so it might be impossible to
1855 represent the PostgreSQL user name in UTF-8.
1856 </para>
1857
1858 <para>
1859 The SCRAM specification dictates that the password is also in UTF-8, and is
1860 processed with the <firstterm>SASLprep</firstterm> algorithm.
1861 <productname>PostgreSQL</productname>, however, does not require UTF-8 to be used for
1862 the password. When a user's password is set, it is processed with SASLprep
1863 as if it was in UTF-8, regardless of the actual encoding used. However, if
1864 it is not a legal UTF-8 byte sequence, or it contains UTF-8 byte sequences
1865 that are prohibited by the SASLprep algorithm, the raw password will be used
1866 without SASLprep processing, instead of throwing an error. This allows the
1867 password to be normalized when it is in UTF-8, but still allows a non-UTF-8
1868 password to be used, and doesn't require the system to know which encoding
1869 the password is in.
1870 </para>
1871
1872 <para>
1873 <firstterm>Channel binding</firstterm> is supported in PostgreSQL builds with
1874 SSL support. The SASL mechanism name for SCRAM with channel binding is
1875 <literal>SCRAM-SHA-256-PLUS</literal>. The channel binding type used by
1876 PostgreSQL is <literal>tls-server-end-point</literal>.
1877 </para>
1878
1879 <para>
1880 In <acronym>SCRAM</acronym> without channel binding, the server chooses
1881 a random number that is transmitted to the client to be mixed with the
1882 user-supplied password in the transmitted password hash. While this
1883 prevents the password hash from being successfully retransmitted in
1884 a later session, it does not prevent a fake server between the real
1885 server and client from passing through the server's random value
1886 and successfully authenticating.
1887 </para>
1888
1889 <para>
1890 <acronym>SCRAM</acronym> with channel binding prevents such
1891 man-in-the-middle attacks by mixing the signature of the server's
1892 certificate into the transmitted password hash. While a fake server can
1893 retransmit the real server's certificate, it doesn't have access to the
1894 private key matching that certificate, and therefore cannot prove it is
1895 the owner, causing SSL connection failure.
1896 </para>
1897
1898 <procedure>
1899 <title>Example</title>
1900 <step id="scram-begin">
1901 <para>
1902 The server sends an AuthenticationSASL message. It includes a list of
1903 SASL authentication mechanisms that the server can accept.
1904 This will be <literal>SCRAM-SHA-256-PLUS</literal>
1905 and <literal>SCRAM-SHA-256</literal> if the server is built with SSL
1906 support, or else just the latter.
1907 </para>
1908 </step>
1909
1910 <step id="scram-client-first">
1911 <para>
1912 The client responds by sending a SASLInitialResponse message, which
1913 indicates the chosen mechanism, <literal>SCRAM-SHA-256</literal> or
1914 <literal>SCRAM-SHA-256-PLUS</literal>. (A client is free to choose either
1915 mechanism, but for better security it should choose the channel-binding
1916 variant if it can support it.) In the Initial Client response field, the
1917 message contains the SCRAM <structname>client-first-message</structname>.
1918 The <structname>client-first-message</structname> also contains the channel
1919 binding type chosen by the client.
1920 </para>
1921 </step>
1922
1923 <step id="scram-server-first">
1924 <para>
1925 Server sends an AuthenticationSASLContinue message, with a SCRAM
1926 <structname>server-first-message</structname> as the content.
1927 </para>
1928 </step>
1929
1930 <step id="scram-client-final">
1931 <para>
1932 Client sends a SASLResponse message, with SCRAM
1933 <structname>client-final-message</structname> as the content.
1934 </para>
1935 </step>
1936
1937 <step id="scram-server-final">
1938 <para>
1939 Server sends an AuthenticationSASLFinal message, with the SCRAM
1940 <structname>server-final-message</structname>, followed immediately by
1941 an AuthenticationOk message.
1942 </para>
1943 </step>
1944 </procedure>
1945 </sect2>
1946
1947 <sect2 id="sasl-oauthbearer">
1948 <title>OAUTHBEARER Authentication</title>
1949
1950 <para>
1951 <literal>OAUTHBEARER</literal> is a token-based mechanism for federated
1952 authentication. It is described in detail in
1953 <ulink url="https://datatracker.ietf.org/doc/html/rfc7628">RFC 7628</ulink>.
1954 </para>
1955
1956 <para>
1957 A typical exchange differs depending on whether or not the client already
1958 has a bearer token cached for the current user. If it does not, the exchange
1959 will take place over two connections: the first "discovery" connection to
1960 obtain OAuth metadata from the server, and the second connection to send
1961 the token after the client has obtained it. (libpq does not currently
1962 implement a caching method as part of its builtin flow, so it uses the
1963 two-connection exchange.)
1964 </para>
1965
1966 <para>
1967 This mechanism is client-initiated, like SCRAM. The client initial response
1968 consists of the standard "GS2" header used by SCRAM, followed by a list of
1969 <literal>key=value</literal> pairs. The only key currently supported by
1970 the server is <literal>auth</literal>, which contains the bearer token.
1971 <literal>OAUTHBEARER</literal> additionally specifies three optional
1972 components of the client initial response (the <literal>authzid</literal> of
1973 the GS2 header, and the <structfield>host</structfield> and
1974 <structfield>port</structfield> keys) which are currently ignored by the
1975 server.
1976 </para>
1977
1978 <para>
1979 <literal>OAUTHBEARER</literal> does not support channel binding, and there
1980 is no "OAUTHBEARER-PLUS" mechanism. This mechanism does not make use of
1981 server data during a successful authentication, so the
1982 AuthenticationSASLFinal message is not used in the exchange.
1983 </para>
1984
1985 <procedure>
1986 <title>Example</title>
1987 <step>
1988 <para>
1989 During the first exchange, the server sends an AuthenticationSASL message
1990 with the <literal>OAUTHBEARER</literal> mechanism advertised.
1991 </para>
1992 </step>
1993
1994 <step>
1995 <para>
1996 The client responds by sending a SASLInitialResponse message which
1997 indicates the <literal>OAUTHBEARER</literal> mechanism. Assuming the
1998 client does not already have a valid bearer token for the current user,
1999 the <structfield>auth</structfield> field is empty, indicating a discovery
2000 connection.
2001 </para>
2002 </step>
2003
2004 <step>
2005 <para>
2006 Server sends an AuthenticationSASLContinue message containing an error
2007 <literal>status</literal> alongside a well-known URI and scopes that the
2008 client should use to conduct an OAuth flow.
2009 </para>
2010 </step>
2011
2012 <step>
2013 <para>
2014 Client sends a SASLResponse message containing the empty set (a single
2015 <literal>0x01</literal> byte) to finish its half of the discovery
2016 exchange.
2017 </para>
2018 </step>
2019
2020 <step>
2021 <para>
2022 Server sends an ErrorMessage to fail the first exchange.
2023 </para>
2024 <para>
2025 At this point, the client conducts one of many possible OAuth flows to
2026 obtain a bearer token, using any metadata that it has been configured with
2027 in addition to that provided by the server. (This description is left
2028 deliberately vague; <literal>OAUTHBEARER</literal> does not specify or
2029 mandate any particular method for obtaining a token.)
2030 </para>
2031 <para>
2032 Once it has a token, the client reconnects to the server for the final
2033 exchange:
2034 </para>
2035 </step>
2036
2037 <step>
2038 <para>
2039 The server once again sends an AuthenticationSASL message with the
2040 <literal>OAUTHBEARER</literal> mechanism advertised.
2041 </para>
2042 </step>
2043
2044 <step>
2045 <para>
2046 The client responds by sending a SASLInitialResponse message, but this
2047 time the <structfield>auth</structfield> field in the message contains the
2048 bearer token that was obtained during the client flow.
2049 </para>
2050 </step>
2051
2052 <step>
2053 <para>
2054 The server validates the token according to the instructions of the
2055 token provider. If the client is authorized to connect, it sends an
2056 AuthenticationOk message to end the SASL exchange.
2057 </para>
2058 </step>
2059 </procedure>
2060 </sect2>
2061 </sect1>
2062
2063 <sect1 id="protocol-replication">
2064 <title>Streaming Replication Protocol</title>
2065
2066 <para>
2067 To initiate streaming replication, the frontend sends the
2068 <literal>replication</literal> parameter in the startup message. A Boolean
2069 value of <literal>true</literal> (or <literal>on</literal>,
2070 <literal>yes</literal>, <literal>1</literal>) tells the backend to go into
2071 physical replication walsender mode, wherein a small set of replication
2072 commands, shown below, can be issued instead of SQL statements.
2073 </para>
2074
2075 <para>
2076 Passing <literal>database</literal> as the value for the
2077 <literal>replication</literal> parameter instructs the backend to go into
2078 logical replication walsender mode, connecting to the database specified in
2079 the <literal>dbname</literal> parameter. In logical replication walsender
2080 mode, the replication commands shown below as well as normal SQL commands can
2081 be issued.
2082 </para>
2083
2084 <para>
2085 In either physical replication or logical replication walsender mode, only the
2086 simple query protocol can be used.
2087 </para>
2088
2089 <para>
2090 For the purpose of testing replication commands, you can make a replication
2091 connection via <application>psql</application> or any other
2092 <application>libpq</application>-using tool with a connection string including
2093 the <literal>replication</literal> option,
2094 e.g.:
2095 <programlisting>
2096 psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
2097 </programlisting>
2098 However, it is often more useful to use
2099 <xref linkend="app-pgreceivewal"/> (for physical replication) or
2100 <xref linkend="app-pgrecvlogical"/> (for logical replication).
2101 </para>
2102
2103 <para>
2104 Replication commands are logged in the server log when
2105 <xref linkend="guc-log-replication-commands"/> is enabled.
2106 </para>
2107
2108 <para>
2109 The commands accepted in replication mode are:
2110
2111 <variablelist>
2112 <varlistentry id="protocol-replication-identify-system">
2113 <term><literal>IDENTIFY_SYSTEM</literal>
2114 <indexterm><primary>IDENTIFY_SYSTEM</primary></indexterm>
2115 </term>
2116 <listitem>
2117 <para>
2118 Requests the server to identify itself. Server replies with a result
2119 set of a single row, containing four fields:
2120 </para>
2121
2122 <variablelist>
2123 <varlistentry>
2124 <term><literal>systemid</literal> (<type>text</type>)</term>
2125 <listitem>
2126 <para>
2127 The unique system identifier identifying the cluster. This
2128 can be used to check that the base backup used to initialize the
2129 standby came from the same cluster.
2130 </para>
2131 </listitem>
2132 </varlistentry>
2133
2134 <varlistentry>
2135 <term><literal>timeline</literal> (<type>int8</type>)</term>
2136 <listitem>
2137 <para>
2138 Current timeline ID. Also useful to check that the standby is
2139 consistent with the primary.
2140 </para>
2141 </listitem>
2142 </varlistentry>
2143
2144 <varlistentry>
2145 <term><literal>xlogpos</literal> (<type>text</type>)</term>
2146 <listitem>
2147 <para>
2148 Current WAL flush location. Useful to get a known location in the
2149 write-ahead log where streaming can start.
2150 </para>
2151 </listitem>
2152 </varlistentry>
2153
2154 <varlistentry>
2155 <term><literal>dbname</literal> (<type>text</type>)</term>
2156 <listitem>
2157 <para>
2158 Database connected to or null.
2159 </para>
2160 </listitem>
2161 </varlistentry>
2162 </variablelist>
2163 </listitem>
2164 </varlistentry>
2165
2166 <varlistentry id="protocol-replication-show">
2167 <term><literal>SHOW</literal> <replaceable class="parameter">name</replaceable>
2168 <indexterm><primary>SHOW</primary></indexterm>
2169 </term>
2170 <listitem>
2171 <para>
2172 Requests the server to send the current setting of a run-time parameter.
2173 This is similar to the SQL command <xref linkend="sql-show"/>.
2174 </para>
2175
2176 <variablelist>
2177 <varlistentry>
2178 <term><replaceable class="parameter">name</replaceable></term>
2179 <listitem>
2180 <para>
2181 The name of a run-time parameter. Available parameters are documented
2182 in <xref linkend="runtime-config"/>.
2183 </para>
2184 </listitem>
2185 </varlistentry>
2186 </variablelist>
2187 </listitem>
2188 </varlistentry>
2189
2190 <varlistentry id="protocol-replication-timeline-history">
2191 <term><literal>TIMELINE_HISTORY</literal> <replaceable class="parameter">tli</replaceable>
2192 <indexterm><primary>TIMELINE_HISTORY</primary></indexterm>
2193 </term>
2194 <listitem>
2195 <para>
2196 Requests the server to send over the timeline history file for timeline
2197 <replaceable class="parameter">tli</replaceable>. Server replies with a
2198 result set of a single row, containing two fields. While the fields
2199 are labeled as <type>text</type>, they effectively return raw bytes,
2200 with no encoding conversion:
2201 </para>
2202
2203 <variablelist>
2204 <varlistentry>
2205 <term><literal>filename</literal> (<type>text</type>)</term>
2206 <listitem>
2207 <para>
2208 File name of the timeline history file, e.g., <filename>00000002.history</filename>.
2209 </para>
2210 </listitem>
2211 </varlistentry>
2212
2213 <varlistentry>
2214 <term><literal>content</literal> (<type>text</type>)</term>
2215 <listitem>
2216 <para>
2217 Contents of the timeline history file.
2218 </para>
2219 </listitem>
2220 </varlistentry>
2221 </variablelist>
2222 </listitem>
2223 </varlistentry>
2224
2225 <varlistentry id="protocol-replication-create-replication-slot" xreflabel="CREATE_REPLICATION_SLOT">
2226 <term><literal>CREATE_REPLICATION_SLOT</literal> <replaceable class="parameter">slot_name</replaceable> [ <literal>TEMPORARY</literal> ] { <literal>PHYSICAL</literal> | <literal>LOGICAL</literal> <replaceable class="parameter">output_plugin</replaceable> } [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ]
2227 <indexterm><primary>CREATE_REPLICATION_SLOT</primary></indexterm>
2228 </term>
2229 <listitem>
2230 <para>
2231 Create a physical or logical replication
2232 slot. See <xref linkend="streaming-replication-slots"/> for more about
2233 replication slots.
2234 </para>
2235
2236 <variablelist>
2237 <varlistentry>
2238 <term><replaceable class="parameter">slot_name</replaceable></term>
2239 <listitem>
2240 <para>
2241 The name of the slot to create. Must be a valid replication slot
2242 name (see <xref linkend="streaming-replication-slots-manipulation"/>).
2243 </para>
2244 </listitem>
2245 </varlistentry>
2246
2247 <varlistentry>
2248 <term><replaceable class="parameter">output_plugin</replaceable></term>
2249 <listitem>
2250 <para>
2251 The name of the output plugin used for logical decoding
2252 (see <xref linkend="logicaldecoding-output-plugin"/>).
2253 </para>
2254 </listitem>
2255 </varlistentry>
2256
2257 <varlistentry>
2258 <term><literal>TEMPORARY</literal></term>
2259 <listitem>
2260 <para>
2261 Specify that this replication slot is a temporary one. Temporary
2262 slots are not saved to disk and are automatically dropped on error
2263 or when the session has finished.
2264 </para>
2265 </listitem>
2266 </varlistentry>
2267 </variablelist>
2268
2269 <para>The following options are supported:</para>
2270
2271 <variablelist>
2272 <varlistentry>
2273 <term><literal>TWO_PHASE [ <replaceable class="parameter">boolean</replaceable> ]</literal></term>
2274 <listitem>
2275 <para>
2276 If true, this logical replication slot supports decoding of two-phase
2277 commit. With this option, commands related to two-phase commit such as
2278 <literal>PREPARE TRANSACTION</literal>, <literal>COMMIT PREPARED</literal>
2279 and <literal>ROLLBACK PREPARED</literal> are decoded and transmitted.
2280 The transaction will be decoded and transmitted at
2281 <literal>PREPARE TRANSACTION</literal> time.
2282 The default is false.
2283 </para>
2284 </listitem>
2285 </varlistentry>
2286
2287 <varlistentry>
2288 <term><literal>RESERVE_WAL [ <replaceable class="parameter">boolean</replaceable> ]</literal></term>
2289 <listitem>
2290 <para>
2291 If true, this physical replication slot reserves <acronym>WAL</acronym>
2292 immediately. Otherwise, <acronym>WAL</acronym> is only reserved upon
2293 connection from a streaming replication client.
2294 The default is false.
2295 </para>
2296 </listitem>
2297 </varlistentry>
2298
2299 <varlistentry>
2300 <term><literal>SNAPSHOT { 'export' | 'use' | 'nothing' }</literal></term>
2301 <listitem>
2302 <para>
2303 Decides what to do with the snapshot created during logical slot
2304 initialization. <literal>'export'</literal>, which is the default,
2305 will export the snapshot for use in other sessions. This option can't
2306 be used inside a transaction. <literal>'use'</literal> will use the
2307 snapshot for the current transaction executing the command. This
2308 option must be used in a transaction, and
2309 <literal>CREATE_REPLICATION_SLOT</literal> must be the first command
2310 run in that transaction. Finally, <literal>'nothing'</literal> will
2311 just use the snapshot for logical decoding as normal but won't do
2312 anything else with it.
2313 </para>
2314 </listitem>
2315 </varlistentry>
2316
2317 <varlistentry>
2318 <term><literal>FAILOVER [ <replaceable class="parameter">boolean</replaceable> ]</literal></term>
2319 <listitem>
2320 <para>
2321 If true, the slot is enabled to be synced to the standbys
2322 so that logical replication can be resumed after failover.
2323 The default is false.
2324 </para>
2325 </listitem>
2326 </varlistentry>
2327 </variablelist>
2328
2329 <para>
2330 In response to this command, the server will send a one-row result set
2331 containing the following fields:
2332
2333 <variablelist>
2334 <varlistentry>
2335 <term><literal>slot_name</literal> (<type>text</type>)</term>
2336 <listitem>
2337 <para>
2338 The name of the newly-created replication slot.
2339 </para>
2340 </listitem>
2341 </varlistentry>
2342
2343 <varlistentry>
2344 <term><literal>consistent_point</literal> (<type>text</type>)</term>
2345 <listitem>
2346 <para>
2347 The WAL location at which the slot became consistent. This is the
2348 earliest location from which streaming can start on this replication
2349 slot.
2350 </para>
2351 </listitem>
2352 </varlistentry>
2353
2354 <varlistentry>
2355 <term><literal>snapshot_name</literal> (<type>text</type>)</term>
2356 <listitem>
2357 <para>
2358 The identifier of the snapshot exported by the command. The
2359 snapshot is valid until a new command is executed on this connection
2360 or the replication connection is closed. Null if the created slot
2361 is physical.
2362 </para>
2363 </listitem>
2364 </varlistentry>
2365
2366 <varlistentry>
2367 <term><literal>output_plugin</literal> (<type>text</type>)</term>
2368 <listitem>
2369 <para>
2370 The name of the output plugin used by the newly-created replication
2371 slot. Null if the created slot is physical.
2372 </para>
2373 </listitem>
2374 </varlistentry>
2375 </variablelist>
2376 </para>
2377 </listitem>
2378 </varlistentry>
2379
2380 <varlistentry id="protocol-replication-create-replication-slot-legacy">
2381 <term><literal>CREATE_REPLICATION_SLOT</literal> <replaceable class="parameter">slot_name</replaceable> [ <literal>TEMPORARY</literal> ] { <literal>PHYSICAL</literal> [ <literal>RESERVE_WAL</literal> ] | <literal>LOGICAL</literal> <replaceable class="parameter">output_plugin</replaceable> [ <literal>EXPORT_SNAPSHOT</literal> | <literal>NOEXPORT_SNAPSHOT</literal> | <literal>USE_SNAPSHOT</literal> | <literal>TWO_PHASE</literal> ] }
2382 </term>
2383 <listitem>
2384 <para>
2385 For compatibility with older releases, this alternative syntax for
2386 the <literal>CREATE_REPLICATION_SLOT</literal> command is still supported.
2387 </para>
2388 </listitem>
2389 </varlistentry>
2390
2391 <varlistentry id="protocol-replication-alter-replication-slot" xreflabel="ALTER_REPLICATION_SLOT">
2392 <term><literal>ALTER_REPLICATION_SLOT</literal> <replaceable class="parameter">slot_name</replaceable> ( <replaceable class="parameter">option</replaceable> [, ...] )
2393 <indexterm><primary>ALTER_REPLICATION_SLOT</primary></indexterm>
2394 </term>
2395 <listitem>
2396 <para>
2397 Change the definition of a replication slot.
2398 See <xref linkend="streaming-replication-slots"/> for more about
2399 replication slots. This command is currently only supported for logical
2400 replication slots.
2401 </para>
2402
2403 <variablelist>
2404 <varlistentry>
2405 <term><replaceable class="parameter">slot_name</replaceable></term>
2406 <listitem>
2407 <para>
2408 The name of the slot to alter. Must be a valid replication slot
2409 name (see <xref linkend="streaming-replication-slots-manipulation"/>).
2410 </para>
2411 </listitem>
2412 </varlistentry>
2413 </variablelist>
2414
2415 <para>The following options are supported:</para>
2416
2417 <variablelist>
2418 <varlistentry>
2419 <term><literal>TWO_PHASE [ <replaceable class="parameter">boolean</replaceable> ]</literal></term>
2420 <listitem>
2421 <para>
2422 If true, this logical replication slot supports decoding of two-phase
2423 commit. With this option, commands related to two-phase commit such as
2424 <literal>PREPARE TRANSACTION</literal>, <literal>COMMIT PREPARED</literal>
2425 and <literal>ROLLBACK PREPARED</literal> are decoded and transmitted.
2426 The transaction will be decoded and transmitted at
2427 <literal>PREPARE TRANSACTION</literal> time.
2428 </para>
2429 </listitem>
2430 </varlistentry>
2431 </variablelist>
2432
2433 <variablelist>
2434 <varlistentry>
2435 <term><literal>FAILOVER [ <replaceable class="parameter">boolean</replaceable> ]</literal></term>
2436 <listitem>
2437 <para>
2438 If true, the slot is enabled to be synced to the standbys
2439 so that logical replication can be resumed after failover.
2440 </para>
2441 </listitem>
2442 </varlistentry>
2443 </variablelist>
2444
2445 </listitem>
2446 </varlistentry>
2447
2448 <varlistentry id="protocol-replication-read-replication-slot">
2449 <term><literal>READ_REPLICATION_SLOT</literal> <replaceable class="parameter">slot_name</replaceable>
2450 <indexterm><primary>READ_REPLICATION_SLOT</primary></indexterm>
2451 </term>
2452 <listitem>
2453 <para>
2454 Read some information associated with a replication slot. Returns a tuple
2455 with <literal>NULL</literal> values if the replication slot does not
2456 exist. This command is currently only supported for physical replication
2457 slots.
2458 </para>
2459
2460 <para>
2461 In response to this command, the server will return a one-row result set,
2462 containing the following fields:
2463 <variablelist>
2464 <varlistentry>
2465 <term><literal>slot_type</literal> (<type>text</type>)</term>
2466 <listitem>
2467 <para>
2468 The replication slot's type, either <literal>physical</literal> or
2469 <literal>NULL</literal>.
2470 </para>
2471 </listitem>
2472 </varlistentry>
2473
2474 <varlistentry>
2475 <term><literal>restart_lsn</literal> (<type>text</type>)</term>
2476 <listitem>
2477 <para>
2478 The replication slot's <literal>restart_lsn</literal>.
2479 </para>
2480 </listitem>
2481 </varlistentry>
2482
2483 <varlistentry>
2484 <term><literal>restart_tli</literal> (<type>int8</type>)</term>
2485 <listitem>
2486 <para>
2487 The timeline ID associated with <literal>restart_lsn</literal>,
2488 following the current timeline history.
2489 </para>
2490 </listitem>
2491 </varlistentry>
2492 </variablelist>
2493 </para>
2494 </listitem>
2495 </varlistentry>
2496
2497 <varlistentry id="protocol-replication-start-replication">
2498 <term><literal>START_REPLICATION</literal> [ <literal>SLOT</literal> <replaceable class="parameter">slot_name</replaceable> ] [ <literal>PHYSICAL</literal> ] <replaceable class="parameter">XXX/XXX</replaceable> [ <literal>TIMELINE</literal> <replaceable class="parameter">tli</replaceable> ]
2499 <indexterm><primary>START_REPLICATION</primary></indexterm>
2500 </term>
2501 <listitem>
2502 <para>
2503 Instructs server to start streaming WAL, starting at
2504 WAL location <replaceable class="parameter">XXX/XXX</replaceable>.
2505 If <literal>TIMELINE</literal> option is specified,
2506 streaming starts on timeline <replaceable class="parameter">tli</replaceable>;
2507 otherwise, the server's current timeline is selected. The server can
2508 reply with an error, for example if the requested section of WAL has already
2509 been recycled. On success, the server responds with a CopyBothResponse
2510 message, and then starts to stream WAL to the frontend.
2511 </para>
2512
2513 <para>
2514 If a slot's name is provided
2515 via <replaceable class="parameter">slot_name</replaceable>, it will be updated
2516 as replication progresses so that the server knows which WAL segments,
2517 and if <varname>hot_standby_feedback</varname> is on which transactions,
2518 are still needed by the standby.
2519 </para>
2520
2521 <para>
2522 If the client requests a timeline that's not the latest but is part of
2523 the history of the server, the server will stream all the WAL on that
2524 timeline starting from the requested start point up to the point where
2525 the server switched to another timeline. If the client requests
2526 streaming at exactly the end of an old timeline, the server skips COPY
2527 mode entirely.
2528 </para>
2529
2530 <para>
2531 After streaming all the WAL on a timeline that is not the latest one,
2532 the server will end streaming by exiting the COPY mode. When the client
2533 acknowledges this by also exiting COPY mode, the server sends a result
2534 set with one row and two columns, indicating the next timeline in this
2535 server's history. The first column is the next timeline's ID (type <type>int8</type>), and the
2536 second column is the WAL location where the switch happened (type <type>text</type>). Usually,
2537 the switch position is the end of the WAL that was streamed, but there
2538 are corner cases where the server can send some WAL from the old
2539 timeline that it has not itself replayed before promoting. Finally, the
2540 server sends two CommandComplete messages (one that ends the CopyData
2541 and the other ends the <literal>START_REPLICATION</literal> itself), and
2542 is ready to accept a new command.
2543 </para>
2544
2545 <para>
2546 WAL data is sent as a series of CopyData messages;
2547 see <xref linkend="protocol-message-types"/> and <xref
2548 linkend="protocol-message-formats"/> for details.
2549 (This allows other information to be intermixed; in particular the server can send
2550 an ErrorResponse message if it encounters a failure after beginning
2551 to stream.) The payload of each CopyData message from server to the
2552 client contains a message of one of the following formats:
2553 </para>
2554
2555 <variablelist>
2556 <varlistentry id="protocol-replication-xlogdata">
2557 <term>XLogData (B)</term>
2558 <listitem>
2559 <variablelist>
2560 <varlistentry>
2561 <term>Byte1('w')</term>
2562 <listitem>
2563 <para>
2564 Identifies the message as WAL data.
2565 </para>
2566 </listitem>
2567 </varlistentry>
2568
2569 <varlistentry>
2570 <term>Int64</term>
2571 <listitem>
2572 <para>
2573 The starting point of the WAL data in this message.
2574 </para>
2575 </listitem>
2576 </varlistentry>
2577
2578 <varlistentry>
2579 <term>Int64</term>
2580 <listitem>
2581 <para>
2582 The current end of WAL on the server.
2583 </para>
2584 </listitem>
2585 </varlistentry>
2586
2587 <varlistentry>
2588 <term>Int64</term>
2589 <listitem>
2590 <para>
2591 The server's system clock at the time of transmission, as
2592 microseconds since midnight on 2000-01-01.
2593 </para>
2594 </listitem>
2595 </varlistentry>
2596
2597 <varlistentry>
2598 <term>Byte<replaceable>n</replaceable></term>
2599 <listitem>
2600 <para>
2601 A section of the WAL data stream.
2602 </para>
2603
2604 <para>
2605 A single WAL record is never split across two XLogData messages.
2606 When a WAL record crosses a WAL page boundary, and is therefore
2607 already split using continuation records, it can be split at the page
2608 boundary. In other words, the first main WAL record and its
2609 continuation records can be sent in different XLogData messages.
2610 </para>
2611 </listitem>
2612 </varlistentry>
2613 </variablelist>
2614 </listitem>
2615 </varlistentry>
2616
2617 <varlistentry id="protocol-replication-primary-keepalive-message">
2618 <term>Primary keepalive message (B)</term>
2619 <listitem>
2620 <variablelist>
2621 <varlistentry>
2622 <term>Byte1('k')</term>
2623 <listitem>
2624 <para>
2625 Identifies the message as a sender keepalive.
2626 </para>
2627 </listitem>
2628 </varlistentry>
2629
2630 <varlistentry>
2631 <term>Int64</term>
2632 <listitem>
2633 <para>
2634 The current end of WAL on the server.
2635 </para>
2636 </listitem>
2637 </varlistentry>
2638
2639 <varlistentry>
2640 <term>Int64</term>
2641 <listitem>
2642 <para>
2643 The server's system clock at the time of transmission, as
2644 microseconds since midnight on 2000-01-01.
2645 </para>
2646 </listitem>
2647 </varlistentry>
2648
2649 <varlistentry>
2650 <term>Byte1</term>
2651 <listitem>
2652 <para>
2653 1 means that the client should reply to this message as soon as
2654 possible, to avoid a timeout disconnect. 0 otherwise.
2655 </para>
2656 </listitem>
2657 </varlistentry>
2658 </variablelist>
2659 </listitem>
2660 </varlistentry>
2661 </variablelist>
2662
2663 <para>
2664 The receiving process can send replies back to the sender at any time,
2665 using one of the following message formats (also in the payload of a
2666 CopyData message):
2667 </para>
2668
2669 <variablelist>
2670 <varlistentry id="protocol-replication-standby-status-update">
2671 <term>Standby status update (F)</term>
2672 <listitem>
2673 <variablelist>
2674 <varlistentry>
2675 <term>Byte1('r')</term>
2676 <listitem>
2677 <para>
2678 Identifies the message as a receiver status update.
2679 </para>
2680 </listitem>
2681 </varlistentry>
2682
2683 <varlistentry>
2684 <term>Int64</term>
2685 <listitem>
2686 <para>
2687 The location of the last WAL byte + 1 received and written to disk
2688 in the standby.
2689 </para>
2690 </listitem>
2691 </varlistentry>
2692
2693 <varlistentry>
2694 <term>Int64</term>
2695 <listitem>
2696 <para>
2697 The location of the last WAL byte + 1 flushed to disk in
2698 the standby.
2699 </para>
2700 </listitem>
2701 </varlistentry>
2702
2703 <varlistentry>
2704 <term>Int64</term>
2705 <listitem>
2706 <para>
2707 The location of the last WAL byte + 1 applied in the standby.
2708 </para>
2709 </listitem>
2710 </varlistentry>
2711
2712 <varlistentry>
2713 <term>Int64</term>
2714 <listitem>
2715 <para>
2716 The client's system clock at the time of transmission, as
2717 microseconds since midnight on 2000-01-01.
2718 </para>
2719 </listitem>
2720 </varlistentry>
2721
2722 <varlistentry>
2723 <term>Byte1</term>
2724 <listitem>
2725 <para>
2726 If 1, the client requests the server to reply to this message
2727 immediately. This can be used to ping the server, to test if
2728 the connection is still healthy.
2729 </para>
2730 </listitem>
2731 </varlistentry>
2732 </variablelist>
2733 </listitem>
2734 </varlistentry>
2735
2736 <varlistentry id="protocol-replication-hot-standby-feedback-message">
2737 <term>Hot standby feedback message (F)</term>
2738 <listitem>
2739 <variablelist>
2740 <varlistentry>
2741 <term>Byte1('h')</term>
2742 <listitem>
2743 <para>
2744 Identifies the message as a hot standby feedback message.
2745 </para>
2746 </listitem>
2747 </varlistentry>
2748
2749 <varlistentry>
2750 <term>Int64</term>
2751 <listitem>
2752 <para>
2753 The client's system clock at the time of transmission, as
2754 microseconds since midnight on 2000-01-01.
2755 </para>
2756 </listitem>
2757 </varlistentry>
2758
2759 <varlistentry>
2760 <term>Int32</term>
2761 <listitem>
2762 <para>
2763 The standby's current global <literal>xmin</literal>, excluding the
2764 <literal>catalog_xmin</literal> from any replication slots. If both
2765 this value and the following <literal>catalog_xmin</literal>
2766 are 0, this is treated as a notification that hot standby feedback
2767 will no longer be sent on this connection. Later non-zero messages
2768 may reinitiate the feedback mechanism.
2769 </para>
2770 </listitem>
2771 </varlistentry>
2772
2773 <varlistentry>
2774 <term>Int32</term>
2775 <listitem>
2776 <para>
2777 The epoch of the global <literal>xmin</literal> xid on the standby.
2778 </para>
2779 </listitem>
2780 </varlistentry>
2781
2782 <varlistentry>
2783 <term>Int32</term>
2784 <listitem>
2785 <para>
2786 The lowest <literal>catalog_xmin</literal> of any replication
2787 slots on the standby. Set to 0 if no <literal>catalog_xmin</literal>
2788 exists on the standby or if hot standby feedback is being
2789 disabled.
2790 </para>
2791 </listitem>
2792 </varlistentry>
2793
2794 <varlistentry>
2795 <term>Int32</term>
2796 <listitem>
2797 <para>
2798 The epoch of the <literal>catalog_xmin</literal> xid on the standby.
2799 </para>
2800 </listitem>
2801 </varlistentry>
2802 </variablelist>
2803 </listitem>
2804 </varlistentry>
2805 </variablelist>
2806 </listitem>
2807 </varlistentry>
2808
2809 <varlistentry id="protocol-replication-start-replication-slot-logical">
2810 <term><literal>START_REPLICATION</literal> <literal>SLOT</literal> <replaceable class="parameter">slot_name</replaceable> <literal>LOGICAL</literal> <replaceable class="parameter">XXX/XXX</replaceable> [ ( <replaceable>option_name</replaceable> [ <replaceable>option_value</replaceable> ] [, ...] ) ]</term>
2811 <listitem>
2812 <para>
2813 Instructs server to start streaming WAL for logical replication,
2814 starting at either WAL location <replaceable
2815 class="parameter">XXX/XXX</replaceable> or the slot's
2816 <literal>confirmed_flush_lsn</literal> (see <xref
2817 linkend="view-pg-replication-slots"/>), whichever is greater. This
2818 behavior makes it easier for clients to avoid updating their local LSN
2819 status when there is no data to process. However, starting at a
2820 different LSN than requested might not catch certain kinds of client
2821 errors; so the client may wish to check that
2822 <literal>confirmed_flush_lsn</literal> matches its expectations before
2823 issuing <literal>START_REPLICATION</literal>.
2824 </para>
2825
2826 <para>
2827 The server can reply with an error, for example if the
2828 slot does not exist. On success, the server responds with a CopyBothResponse
2829 message, and then starts to stream WAL to the frontend.
2830 </para>
2831
2832 <para>
2833 The messages inside the CopyBothResponse messages are of the same format
2834 documented for <literal>START_REPLICATION ... PHYSICAL</literal>, including
2835 two CommandComplete messages.
2836 </para>
2837
2838 <para>
2839 The output plugin associated with the selected slot is used
2840 to process the output for streaming.
2841 </para>
2842
2843 <variablelist>
2844 <varlistentry>
2845 <term><literal>SLOT</literal> <replaceable class="parameter">slot_name</replaceable></term>
2846 <listitem>
2847 <para>
2848 The name of the slot to stream changes from. This parameter is required,
2849 and must correspond to an existing logical replication slot created
2850 with <literal>CREATE_REPLICATION_SLOT</literal> in
2851 <literal>LOGICAL</literal> mode.
2852 </para>
2853 </listitem>
2854 </varlistentry>
2855
2856 <varlistentry>
2857 <term><replaceable class="parameter">XXX/XXX</replaceable></term>
2858 <listitem>
2859 <para>
2860 The WAL location to begin streaming at.
2861 </para>
2862 </listitem>
2863 </varlistentry>
2864
2865 <varlistentry>
2866 <term><replaceable class="parameter">option_name</replaceable></term>
2867 <listitem>
2868 <para>
2869 The name of an option passed to the slot's logical decoding output
2870 plugin. See <xref linkend="protocol-logical-replication"/> for
2871 options that are accepted by the standard (<literal>pgoutput</literal>)
2872 plugin.
2873 </para>
2874 </listitem>
2875 </varlistentry>
2876
2877 <varlistentry>
2878 <term><replaceable class="parameter">option_value</replaceable></term>
2879 <listitem>
2880 <para>
2881 Optional value, in the form of a string constant, associated with the
2882 specified option.
2883 </para>
2884 </listitem>
2885 </varlistentry>
2886 </variablelist>
2887 </listitem>
2888 </varlistentry>
2889
2890 <varlistentry id="protocol-replication-drop-replication-slot">
2891 <term>
2892 <literal>DROP_REPLICATION_SLOT</literal> <replaceable class="parameter">slot_name</replaceable> <optional> <literal>WAIT</literal> </optional>
2893 <indexterm><primary>DROP_REPLICATION_SLOT</primary></indexterm>
2894 </term>
2895 <listitem>
2896 <para>
2897 Drops a replication slot, freeing any reserved server-side resources.
2898 </para>
2899
2900 <variablelist>
2901 <varlistentry>
2902 <term><replaceable class="parameter">slot_name</replaceable></term>
2903 <listitem>
2904 <para>
2905 The name of the slot to drop.
2906 </para>
2907 </listitem>
2908 </varlistentry>
2909
2910 <varlistentry>
2911 <term><literal>WAIT</literal></term>
2912 <listitem>
2913 <para>
2914 This option causes the command to wait if the slot is active until
2915 it becomes inactive, instead of the default behavior of raising an
2916 error.
2917 </para>
2918 </listitem>
2919 </varlistentry>
2920 </variablelist>
2921 </listitem>
2922 </varlistentry>
2923
2924 <varlistentry id="protocol-replication-upload-manifest">
2925 <term>
2926 <literal>UPLOAD_MANIFEST</literal>
2927 <indexterm><primary>UPLOAD_MANIFEST</primary></indexterm>
2928 </term>
2929 <listitem>
2930 <para>
2931 Uploads a backup manifest in preparation for taking an incremental
2932 backup.
2933 </para>
2934 </listitem>
2935 </varlistentry>
2936
2937 <varlistentry id="protocol-replication-base-backup" xreflabel="BASE_BACKUP">
2938 <term><literal>BASE_BACKUP</literal> [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ]
2939 <indexterm><primary>BASE_BACKUP</primary></indexterm>
2940 </term>
2941 <listitem>
2942 <para>
2943 Instructs the server to start streaming a base backup.
2944 The system will automatically be put in backup mode before the backup
2945 is started, and taken out of it when the backup is complete. The
2946 following options are accepted:
2947
2948 <variablelist>
2949 <varlistentry>
2950 <term><literal>LABEL</literal> <replaceable>'label'</replaceable></term>
2951 <listitem>
2952 <para>
2953 Sets the label of the backup. If none is specified, a backup label
2954 of <literal>base backup</literal> will be used. The quoting rules
2955 for the label are the same as a standard SQL string with
2956 <xref linkend="guc-standard-conforming-strings"/> turned on.
2957 </para>
2958 </listitem>
2959 </varlistentry>
2960
2961 <varlistentry>
2962 <term><literal>TARGET</literal> <replaceable>'target'</replaceable></term>
2963 <listitem>
2964 <para>
2965 Tells the server where to send the backup. If the target is
2966 <literal>client</literal>, which is the default, the backup data is
2967 sent to the client. If it is <literal>server</literal>, the backup
2968 data is written to the server at the pathname specified by the
2969 <literal>TARGET_DETAIL</literal> option. If it is
2970 <literal>blackhole</literal>, the backup data is not sent
2971 anywhere; it is simply discarded.
2972 </para>
2973
2974 <para>
2975 The <literal>server</literal> target requires superuser privilege or
2976 being granted the <literal>pg_write_server_files</literal> role.
2977 </para>
2978 </listitem>
2979 </varlistentry>
2980
2981 <varlistentry>
2982 <term><literal>TARGET_DETAIL</literal> <replaceable>'detail'</replaceable></term>
2983 <listitem>
2984 <para>
2985 Provides additional information about the backup target.
2986 </para>
2987
2988 <para>
2989 Currently, this option can only be used when the backup target is
2990 <literal>server</literal>. It specifies the server directory
2991 to which the backup should be written.
2992 </para>
2993 </listitem>
2994 </varlistentry>
2995
2996 <varlistentry>
2997 <term><literal>PROGRESS [ <replaceable class="parameter">boolean</replaceable> ]</literal></term>
2998 <listitem>
2999 <para>
3000 If set to true, request information required to generate a progress
3001 report. This will send back an approximate size in the header of each
3002 tablespace, which can be used to calculate how far along the stream
3003 is done. This is calculated by enumerating all the file sizes once
3004 before the transfer is even started, and might as such have a
3005 negative impact on the performance. In particular, it might take
3006 longer before the first data
3007 is streamed. Since the database files can change during the backup,
3008 the size is only approximate and might both grow and shrink between
3009 the time of approximation and the sending of the actual files.
3010 The default is false.
3011 </para>
3012 </listitem>
3013 </varlistentry>
3014
3015 <varlistentry>
3016 <term><literal>CHECKPOINT { 'fast' | 'spread' }</literal></term>
3017 <listitem>
3018 <para>
3019 Sets the type of checkpoint to be performed at the beginning of the
3020 base backup. The default is <literal>spread</literal>.
3021 </para>
3022 </listitem>
3023 </varlistentry>
3024
3025 <varlistentry>
3026 <term><literal>WAL [ <replaceable class="parameter">boolean</replaceable> ]</literal></term>
3027 <listitem>
3028 <para>
3029 If set to true, include the necessary WAL segments in the backup.
3030 This will include all the files between start and stop backup in the
3031 <filename>pg_wal</filename> directory of the base directory tar
3032 file. The default is false.
3033 </para>
3034 </listitem>
3035 </varlistentry>
3036
3037 <varlistentry>
3038 <term><literal>WAIT [ <replaceable class="parameter">boolean</replaceable> ]</literal></term>
3039 <listitem>
3040 <para>
3041 If set to true, the backup will wait until the last required WAL
3042 segment has been archived, or emit a warning if WAL archiving is
3043 not enabled. If false, the backup will neither wait nor warn,
3044 leaving the client responsible for ensuring the required log is
3045 available. The default is true.
3046 </para>
3047 </listitem>
3048 </varlistentry>
3049
3050 <varlistentry>
3051 <term><literal>COMPRESSION</literal> <replaceable>'method'</replaceable></term>
3052 <listitem>
3053 <para>
3054 Instructs the server to compress the backup using the specified
3055 method. Currently, the supported methods are <literal>gzip</literal>,
3056 <literal>lz4</literal>, and <literal>zstd</literal>.
3057 </para>
3058 </listitem>
3059 </varlistentry>
3060
3061 <varlistentry>
3062 <term><literal>COMPRESSION_DETAIL</literal> <replaceable>detail</replaceable></term>
3063 <listitem>
3064 <para>
3065 Specifies details for the chosen compression method. This should only
3066 be used in conjunction with the <literal>COMPRESSION</literal>
3067 option. If the value is an integer, it specifies the compression
3068 level. Otherwise, it should be a comma-separated list of items,
3069 each of the form <replaceable>keyword</replaceable> or
3070 <replaceable>keyword=value</replaceable>. Currently, the supported
3071 keywords are <literal>level</literal>, <literal>long</literal> and
3072 <literal>workers</literal>.
3073 </para>
3074
3075 <para>
3076 The <literal>level</literal> keyword sets the compression level.
3077 For <literal>gzip</literal> the compression level should be an
3078 integer between <literal>1</literal> and <literal>9</literal>
3079 (default <literal>Z_DEFAULT_COMPRESSION</literal> or
3080 <literal>-1</literal>), for <literal>lz4</literal> an integer
3081 between 1 and 12 (default <literal>0</literal> for fast compression
3082 mode), and for <literal>zstd</literal> an integer between
3083 <literal>ZSTD_minCLevel()</literal> (usually <literal>-131072</literal>)
3084 and <literal>ZSTD_maxCLevel()</literal> (usually <literal>22</literal>),
3085 (default <literal>ZSTD_CLEVEL_DEFAULT</literal> or
3086 <literal>3</literal>).
3087 </para>
3088
3089 <para>
3090 The <literal>long</literal> keyword enables long-distance matching
3091 mode, for improved compression ratio, at the expense of higher memory
3092 use. Long-distance mode is supported only for
3093 <literal>zstd</literal>.
3094 </para>
3095
3096 <para>
3097 The <literal>workers</literal> keyword sets the number of threads
3098 that should be used for parallel compression. Parallel compression
3099 is supported only for <literal>zstd</literal>.
3100 </para>
3101 </listitem>
3102 </varlistentry>
3103
3104 <varlistentry>
3105 <term><literal>MAX_RATE</literal> <replaceable>rate</replaceable></term>
3106 <listitem>
3107 <para>
3108 Limit (throttle) the maximum amount of data transferred from server
3109 to client per unit of time. The expected unit is kilobytes per second.
3110 If this option is specified, the value must either be equal to zero
3111 or it must fall within the range from 32 kB through 1 GB (inclusive).
3112 If zero is passed or the option is not specified, no restriction is
3113 imposed on the transfer.
3114 </para>
3115 </listitem>
3116 </varlistentry>
3117
3118 <varlistentry>
3119 <term><literal>TABLESPACE_MAP [ <replaceable class="parameter">boolean</replaceable> ]</literal></term>
3120 <listitem>
3121 <para>
3122 If true, include information about symbolic links present in the
3123 directory <filename>pg_tblspc</filename> in a file named
3124 <filename>tablespace_map</filename>. The tablespace map file includes
3125 each symbolic link name as it exists in the directory
3126 <filename>pg_tblspc/</filename> and the full path of that symbolic link.
3127 The default is false.
3128 </para>
3129 </listitem>
3130 </varlistentry>
3131
3132 <varlistentry>
3133 <term><literal>VERIFY_CHECKSUMS [ <replaceable class="parameter">boolean</replaceable> ]</literal></term>
3134 <listitem>
3135 <para>
3136 If true, checksums are verified during a base backup if they are
3137 enabled. If false, this is skipped. The default is true.
3138 </para>
3139 </listitem>
3140 </varlistentry>
3141
3142 <varlistentry>
3143 <term><literal>MANIFEST</literal> <replaceable>manifest_option</replaceable></term>
3144 <listitem>
3145 <para>
3146 When this option is specified with a value of <literal>yes</literal>
3147 or <literal>force-encode</literal>, a backup manifest is created
3148 and sent along with the backup. The manifest is a list of every
3149 file present in the backup with the exception of any WAL files that
3150 may be included. It also stores the size, last modification time, and
3151 optionally a checksum for each file.
3152 A value of <literal>force-encode</literal> forces all filenames
3153 to be hex-encoded; otherwise, this type of encoding is performed only
3154 for files whose names are non-UTF8 octet sequences.
3155 <literal>force-encode</literal> is intended primarily for testing
3156 purposes, to be sure that clients which read the backup manifest
3157 can handle this case. For compatibility with previous releases,
3158 the default is <literal>MANIFEST 'no'</literal>.
3159 </para>
3160 </listitem>
3161 </varlistentry>
3162
3163 <varlistentry>
3164 <term><literal>MANIFEST_CHECKSUMS</literal> <replaceable>checksum_algorithm</replaceable></term>
3165 <listitem>
3166 <para>
3167 Specifies the checksum algorithm that should be applied to each file included
3168 in the backup manifest. Currently, the available
3169 algorithms are <literal>NONE</literal>, <literal>CRC32C</literal>,
3170 <literal>SHA224</literal>, <literal>SHA256</literal>,
3171 <literal>SHA384</literal>, and <literal>SHA512</literal>.
3172 The default is <literal>CRC32C</literal>.
3173 </para>
3174 </listitem>
3175 </varlistentry>
3176
3177 <varlistentry>
3178 <term><literal>INCREMENTAL</literal></term>
3179 <listitem>
3180 <para>
3181 Requests an incremental backup. The
3182 <literal>UPLOAD_MANIFEST</literal> command must be executed
3183 before running a base backup with this option.
3184 </para>
3185 </listitem>
3186 </varlistentry>
3187 </variablelist>
3188 </para>
3189
3190 <para>
3191 When the backup is started, the server will first send two
3192 ordinary result sets, followed by one or more CopyOutResponse
3193 results.
3194 </para>
3195
3196 <para>
3197 The first ordinary result set contains the starting position of the
3198 backup, in a single row with two columns. The first column contains
3199 the start position given in XLogRecPtr format, and the second column
3200 contains the corresponding timeline ID.
3201 </para>
3202
3203 <para>
3204 The second ordinary result set has one row for each tablespace.
3205 The fields in this row are:
3206
3207 <variablelist>
3208 <varlistentry>
3209 <term><literal>spcoid</literal> (<type>oid</type>)</term>
3210 <listitem>
3211 <para>
3212 The OID of the tablespace, or null if it's the base
3213 directory.
3214 </para>
3215 </listitem>
3216 </varlistentry>
3217
3218 <varlistentry>
3219 <term><literal>spclocation</literal> (<type>text</type>)</term>
3220 <listitem>
3221 <para>
3222 The full path of the tablespace directory, or null
3223 if it's the base directory.
3224 </para>
3225 </listitem>
3226 </varlistentry>
3227
3228 <varlistentry>
3229 <term><literal>size</literal> (<type>int8</type>)</term>
3230 <listitem>
3231 <para>
3232 The approximate size of the tablespace, in kilobytes (1024 bytes),
3233 if progress report has been requested; otherwise it's null.
3234 </para>
3235 </listitem>
3236 </varlistentry>
3237 </variablelist>
3238 </para>
3239
3240 <para>
3241 After the second regular result set, a CopyOutResponse will be sent.
3242 The payload of each CopyData message will contain a message in one of
3243 the following formats:
3244 </para>
3245
3246 <variablelist>
3247 <varlistentry>
3248 <term>new archive (B)</term>
3249 <listitem>
3250 <variablelist>
3251 <varlistentry>
3252 <term>Byte1('n')</term>
3253 <listitem><para>
3254 Identifies the message as indicating the start of a new archive.
3255 There will be one archive for the main data directory and one
3256 for each additional tablespace; each will use tar format
3257 (following the <quote>ustar interchange format</quote> specified
3258 in the POSIX 1003.1-2008 standard).
3259 </para></listitem>
3260 </varlistentry>
3261
3262 <varlistentry>
3263 <term>String</term>
3264 <listitem><para>
3265 The file name for this archive.
3266 </para></listitem>
3267 </varlistentry>
3268
3269 <varlistentry>
3270 <term>String</term>
3271 <listitem><para>
3272 For the main data directory, an empty string. For other
3273 tablespaces, the full path to the directory from which this
3274 archive was created.
3275 </para></listitem>
3276 </varlistentry>
3277 </variablelist>
3278 </listitem>
3279 </varlistentry>
3280
3281 <varlistentry>
3282 <term>manifest (B)</term>
3283 <listitem>
3284 <variablelist>
3285 <varlistentry>
3286 <term>Byte1('m')</term>
3287 <listitem><para>
3288 Identifies the message as indicating the start of the backup
3289 manifest.
3290 </para></listitem>
3291 </varlistentry>
3292 </variablelist>
3293 </listitem>
3294 </varlistentry>
3295
3296 <varlistentry>
3297 <term>archive or manifest data (B)</term>
3298 <listitem>
3299 <variablelist>
3300 <varlistentry>
3301 <term>Byte1('d')</term>
3302 <listitem><para>
3303 Identifies the message as containing archive or manifest data.
3304 </para></listitem>
3305 </varlistentry>
3306
3307 <varlistentry>
3308 <term>Byte<replaceable>n</replaceable></term>
3309 <listitem><para>
3310 Data bytes.
3311 </para></listitem>
3312 </varlistentry>
3313 </variablelist>
3314 </listitem>
3315 </varlistentry>
3316
3317 <varlistentry>
3318 <term>progress report (B)</term>
3319 <listitem>
3320 <variablelist>
3321 <varlistentry>
3322 <term>Byte1('p')</term>
3323 <listitem><para>
3324 Identifies the message as a progress report.
3325 </para></listitem>
3326 </varlistentry>
3327
3328 <varlistentry>
3329 <term>Int64</term>
3330 <listitem><para>
3331 The number of bytes from the current tablespace for which
3332 processing has been completed.
3333 </para></listitem>
3334 </varlistentry>
3335 </variablelist>
3336 </listitem>
3337 </varlistentry>
3338 </variablelist>
3339
3340 <para>
3341 After the CopyOutResponse, or all such responses, have been sent, a
3342 final ordinary result set will be sent, containing the WAL end position
3343 of the backup, in the same format as the start position.
3344 </para>
3345
3346 <para>
3347 The tar archive for the data directory and each tablespace will contain
3348 all files in the directories, regardless of whether they are
3349 <productname>PostgreSQL</productname> files or other files added to the same
3350 directory. The only excluded files are:
3351
3352 <itemizedlist spacing="compact" mark="bullet">
3353 <listitem>
3354 <para>
3355 <filename>postmaster.pid</filename>
3356 </para>
3357 </listitem>
3358 <listitem>
3359 <para>
3360 <filename>postmaster.opts</filename>
3361 </para>
3362 </listitem>
3363 <listitem>
3364 <para>
3365 <filename>pg_internal.init</filename> (found in multiple directories)
3366 </para>
3367 </listitem>
3368 <listitem>
3369 <para>
3370 Various temporary files and directories created during the operation
3371 of the PostgreSQL server, such as any file or directory beginning
3372 with <filename>pgsql_tmp</filename> and temporary relations.
3373 </para>
3374 </listitem>
3375 <listitem>
3376 <para>
3377 Unlogged relations, except for the init fork which is required to
3378 recreate the (empty) unlogged relation on recovery.
3379 </para>
3380 </listitem>
3381 <listitem>
3382 <para>
3383 <filename>pg_wal</filename>, including subdirectories. If the backup is run
3384 with WAL files included, a synthesized version of <filename>pg_wal</filename> will be
3385 included, but it will only contain the files necessary for the
3386 backup to work, not the rest of the contents.
3387 </para>
3388 </listitem>
3389 <listitem>
3390 <para>
3391 <filename>pg_dynshmem</filename>, <filename>pg_notify</filename>,
3392 <filename>pg_replslot</filename>, <filename>pg_serial</filename>,
3393 <filename>pg_snapshots</filename>, <filename>pg_stat_tmp</filename>, and
3394 <filename>pg_subtrans</filename> are copied as empty directories (even if
3395 they are symbolic links).
3396 </para>
3397 </listitem>
3398 <listitem>
3399 <para>
3400 Files other than regular files and directories, such as symbolic
3401 links (other than for the directories listed above) and special
3402 device and operating system files, are skipped. (Symbolic links
3403 in <filename>pg_tblspc</filename> are maintained.)
3404 </para>
3405 </listitem>
3406 </itemizedlist>
3407 Owner, group, and file mode are set if the underlying file system on
3408 the server supports it.
3409 </para>
3410 </listitem>
3411 </varlistentry>
3412 </variablelist>
3413 </para>
3414
3415 <para>
3416 In all the above commands,
3417 when specifying a parameter of type <type>boolean</type> the
3418 <replaceable class="parameter">value</replaceable> part can be omitted,
3419 which is equivalent to specifying <literal>TRUE</literal>.
3420 </para>
3421 </sect1>
3422
3423 <sect1 id="protocol-logical-replication">
3424 <title>Logical Streaming Replication Protocol</title>
3425
3426 <para>
3427 This section describes the logical replication protocol, which is the message
3428 flow started by the <literal>START_REPLICATION</literal>
3429 <literal>SLOT</literal> <replaceable class="parameter">slot_name</replaceable>
3430 <literal>LOGICAL</literal> replication command.
3431 </para>
3432
3433 <para>
3434 The logical streaming replication protocol builds on the primitives of
3435 the physical streaming replication protocol.
3436 </para>
3437
3438 <para>
3439 <productname>PostgreSQL</productname> logical decoding supports output
3440 plugins. <literal>pgoutput</literal> is the standard one used for
3441 the built-in logical replication.
3442 </para>
3443
3444 <sect2 id="protocol-logical-replication-params">
3445 <title>Logical Streaming Replication Parameters</title>
3446
3447 <para>
3448 Using the <literal>START_REPLICATION</literal> command,
3449 <literal>pgoutput</literal> accepts the following options:
3450
3451 <variablelist>
3452 <varlistentry>
3453 <term>
3454 proto_version
3455 </term>
3456 <listitem>
3457 <para>
3458 Protocol version. Currently versions <literal>1</literal>, <literal>2</literal>,
3459 <literal>3</literal>, and <literal>4</literal> are supported. A valid
3460 version is required.
3461 </para>
3462 <para>
3463 Version <literal>2</literal> is supported only for server version 14
3464 and above, and it allows streaming of large in-progress transactions.
3465 </para>
3466 <para>
3467 Version <literal>3</literal> is supported only for server version 15
3468 and above, and it allows streaming of two-phase commits.
3469 </para>
3470 <para>
3471 Version <literal>4</literal> is supported only for server version 16
3472 and above, and it allows streams of large in-progress transactions to
3473 be applied in parallel.
3474 </para>
3475 </listitem>
3476 </varlistentry>
3477
3478 <varlistentry>
3479 <term>
3480 publication_names
3481 </term>
3482 <listitem>
3483 <para>
3484 Comma-separated list of publication names for which to subscribe
3485 (receive changes). The individual publication names are treated
3486 as standard objects names and can be quoted the same as needed.
3487 At least one publication name is required.
3488 </para>
3489 </listitem>
3490 </varlistentry>
3491
3492 <varlistentry>
3493 <term>
3494 binary
3495 </term>
3496 <listitem>
3497 <para>
3498 Boolean option to use binary transfer mode. Binary mode is faster
3499 than the text mode but slightly less robust.
3500 </para>
3501 </listitem>
3502 </varlistentry>
3503
3504 <varlistentry>
3505 <term>
3506 messages
3507 </term>
3508 <listitem>
3509 <para>
3510 Boolean option to enable sending the messages that are written
3511 by <function>pg_logical_emit_message</function>.
3512 </para>
3513 </listitem>
3514 </varlistentry>
3515
3516 <varlistentry>
3517 <term>
3518 streaming
3519 </term>
3520 <listitem>
3521 <para>
3522 Option to enable streaming of in-progress transactions. Valid values are
3523 <literal>off</literal> (the default), <literal>on</literal> and
3524 <literal>parallel</literal>. The setting <literal>parallel</literal>
3525 enables sending extra information with some messages to be used for
3526 parallelization. Minimum protocol version 2 is required to turn it
3527 <literal>on</literal>. Minimum protocol version 4 is required for the
3528 <literal>parallel</literal> value.
3529 </para>
3530 </listitem>
3531 </varlistentry>
3532
3533 <varlistentry>
3534 <term>
3535 two_phase
3536 </term>
3537 <listitem>
3538 <para>
3539 Boolean option to enable two-phase transactions. Minimum protocol
3540 version 3 is required to turn it on.
3541 </para>
3542 </listitem>
3543 </varlistentry>
3544
3545 <varlistentry>
3546 <term>
3547 origin
3548 </term>
3549 <listitem>
3550 <para>
3551 Option to send changes by their origin. Possible values are
3552 <literal>none</literal> to only send the changes that have no origin
3553 associated, or <literal>any</literal>
3554 to send the changes regardless of their origin. This can be used
3555 to avoid loops (infinite replication of the same data) among
3556 replication nodes.
3557 </para>
3558 </listitem>
3559 </varlistentry>
3560 </variablelist>
3561
3562 </para>
3563 </sect2>
3564
3565 <sect2 id="protocol-logical-messages">
3566 <title>Logical Replication Protocol Messages</title>
3567
3568 <para>
3569 The individual protocol messages are discussed in the following
3570 subsections. Individual messages are described in
3571 <xref linkend="protocol-logicalrep-message-formats"/>.
3572 </para>
3573
3574 <para>
3575 All top-level protocol messages begin with a message type byte.
3576 While represented in code as a character, this is a signed byte with no
3577 associated encoding.
3578 </para>
3579
3580 <para>
3581 Since the streaming replication protocol supplies a message length there
3582 is no need for top-level protocol messages to embed a length in their
3583 header.
3584 </para>
3585
3586 </sect2>
3587
3588 <sect2 id="protocol-logical-messages-flow">
3589 <title>Logical Replication Protocol Message Flow</title>
3590
3591 <para>
3592 With the exception of the <literal>START_REPLICATION</literal> command and
3593 the replay progress messages, all information flows only from the backend
3594 to the frontend.
3595 </para>
3596
3597 <para>
3598 The logical replication protocol sends individual transactions one by one.
3599 This means that all messages between a pair of Begin and Commit messages
3600 belong to the same transaction. Similarly, all messages between a pair of
3601 Begin Prepare and Prepare messages belong to the same transaction.
3602 It also sends changes of large in-progress transactions between a pair of
3603 Stream Start and Stream Stop messages. The last stream of such a transaction
3604 contains a Stream Commit or Stream Abort message.
3605 </para>
3606
3607 <para>
3608 Every sent transaction contains zero or more DML messages (Insert,
3609 Update, Delete). In case of a cascaded setup it can also contain Origin
3610 messages. The origin message indicates that the transaction originated on
3611 different replication node. Since a replication node in the scope of logical
3612 replication protocol can be pretty much anything, the only identifier
3613 is the origin name. It's downstream's responsibility to handle this as
3614 needed (if needed). The Origin message is always sent before any DML
3615 messages in the transaction.
3616 </para>
3617
3618 <para>
3619 Every DML message contains a relation OID, identifying the publisher's
3620 relation that was acted on. Before the first DML message for a given
3621 relation OID, a Relation message will be sent, describing the schema of
3622 that relation. Subsequently, a new Relation message will be sent if
3623 the relation's definition has changed since the last Relation message
3624 was sent for it. (The protocol assumes that the client is capable of
3625 remembering this metadata for as many relations as needed.)
3626 </para>
3627
3628 <para>
3629 Relation messages identify column types by their OIDs. In the case
3630 of a built-in type, it is assumed that the client can look up that
3631 type OID locally, so no additional data is needed. For a non-built-in
3632 type OID, a Type message will be sent before the Relation message,
3633 to provide the type name associated with that OID. Thus, a client that
3634 needs to specifically identify the types of relation columns should
3635 cache the contents of Type messages, and first consult that cache to
3636 see if the type OID is defined there. If not, look up the type OID
3637 locally.
3638 </para>
3639 </sect2>
3640 </sect1>
3641
3642 <sect1 id="protocol-message-types">
3643 <title>Message Data Types</title>
3644
3645 <para>
3646 This section describes the base data types used in messages.
3647 </para>
3648
3649 <variablelist>
3650 <varlistentry>
3651 <term>Int<replaceable>n</replaceable>(<replaceable>i</replaceable>)</term>
3652 <listitem>
3653 <para>
3654 An <replaceable>n</replaceable>-bit integer in network byte
3655 order (most significant byte first).
3656 If <replaceable>i</replaceable> is specified it
3657 is the exact value that will appear, otherwise the value
3658 is variable. Eg. Int16, Int32(42).
3659 </para>
3660 </listitem>
3661 </varlistentry>
3662
3663 <varlistentry>
3664 <term>Int<replaceable>n</replaceable>[<replaceable>k</replaceable>]</term>
3665 <listitem>
3666 <para>
3667 An array of <replaceable>k</replaceable>
3668 <replaceable>n</replaceable>-bit integers, each in network
3669 byte order. The array length <replaceable>k</replaceable>
3670 is always determined by an earlier field in the message.
3671 Eg. Int16[M].
3672 </para>
3673 </listitem>
3674 </varlistentry>
3675
3676 <varlistentry>
3677 <term>String(<replaceable>s</replaceable>)</term>
3678 <listitem>
3679 <para>
3680 A null-terminated string (C-style string). There is no
3681 specific length limitation on strings.
3682 If <replaceable>s</replaceable> is specified it is the exact
3683 value that will appear, otherwise the value is variable.
3684 Eg. String, String("user").
3685 </para>
3686
3687 <note>
3688 <para>
3689 <emphasis>There is no predefined limit</emphasis> on the length of a string
3690 that can be returned by the backend. Good coding strategy for a frontend
3691 is to use an expandable buffer so that anything that fits in memory can be
3692 accepted. If that's not feasible, read the full string and discard trailing
3693 characters that don't fit into your fixed-size buffer.
3694 </para>
3695 </note>
3696 </listitem>
3697 </varlistentry>
3698
3699 <varlistentry>
3700 <term>Byte<replaceable>n</replaceable>(<replaceable>c</replaceable>)</term>
3701 <listitem>
3702 <para>
3703 Exactly <replaceable>n</replaceable> bytes. If the field
3704 width <replaceable>n</replaceable> is not a constant, it is
3705 always determinable from an earlier field in the message.
3706 If <replaceable>c</replaceable> is specified it is the exact
3707 value. Eg. Byte2, Byte1('\n').
3708 </para>
3709 </listitem>
3710 </varlistentry>
3711 </variablelist>
3712 </sect1>
3713
3714 <sect1 id="protocol-message-formats">
3715 <title>Message Formats</title>
3716
3717 <para>
3718 This section describes the detailed format of each message. Each is marked to
3719 indicate that it can be sent by a frontend (F), a backend (B), or both
3720 (F &amp; B).
3721 Notice that although each message includes a byte count at the beginning,
3722 most messages are defined so that the message end can be found without
3723 reference to the byte count. This is for historical reasons, as the
3724 original, now-obsolete protocol version 2 did not have an explicit length
3725 field. It also aids validity checking though.
3726 </para>
3727
3728 <variablelist>
3729 <varlistentry id="protocol-message-formats-AuthenticationOk">
3730 <term>AuthenticationOk (B)</term>
3731 <listitem>
3732 <variablelist>
3733 <varlistentry>
3734 <term>Byte1('R')</term>
3735 <listitem>
3736 <para>
3737 Identifies the message as an authentication request.
3738 </para>
3739 </listitem>
3740 </varlistentry>
3741
3742 <varlistentry>
3743 <term>Int32(8)</term>
3744 <listitem>
3745 <para>
3746 Length of message contents in bytes, including self.
3747 </para>
3748 </listitem>
3749 </varlistentry>
3750
3751 <varlistentry>
3752 <term>Int32(0)</term>
3753 <listitem>
3754 <para>
3755 Specifies that the authentication was successful.
3756 </para>
3757 </listitem>
3758 </varlistentry>
3759 </variablelist>
3760 </listitem>
3761 </varlistentry>
3762
3763 <varlistentry id="protocol-message-formats-AuthenticationKerberosV5">
3764 <term>AuthenticationKerberosV5 (B)</term>
3765 <listitem>
3766
3767 <variablelist>
3768 <varlistentry>
3769 <term>Byte1('R')</term>
3770 <listitem>
3771 <para>
3772 Identifies the message as an authentication request.
3773 </para>
3774 </listitem>
3775 </varlistentry>
3776
3777 <varlistentry>
3778 <term>Int32(8)</term>
3779 <listitem>
3780 <para>
3781 Length of message contents in bytes, including self.
3782 </para>
3783 </listitem>
3784 </varlistentry>
3785
3786 <varlistentry>
3787 <term>Int32(2)</term>
3788 <listitem>
3789 <para>
3790 Specifies that Kerberos V5 authentication is required.
3791 </para>
3792 </listitem>
3793 </varlistentry>
3794 </variablelist>
3795 </listitem>
3796 </varlistentry>
3797
3798 <varlistentry id="protocol-message-formats-AuthenticationCleartextPassword">
3799 <term>AuthenticationCleartextPassword (B)</term>
3800 <listitem>
3801
3802 <variablelist>
3803 <varlistentry>
3804 <term>Byte1('R')</term>
3805 <listitem>
3806 <para>
3807 Identifies the message as an authentication request.
3808 </para>
3809 </listitem>
3810 </varlistentry>
3811
3812 <varlistentry>
3813 <term>Int32(8)</term>
3814 <listitem>
3815 <para>
3816 Length of message contents in bytes, including self.
3817 </para>
3818 </listitem>
3819 </varlistentry>
3820
3821 <varlistentry>
3822 <term>Int32(3)</term>
3823 <listitem>
3824 <para>
3825 Specifies that a clear-text password is required.
3826 </para>
3827 </listitem>
3828 </varlistentry>
3829 </variablelist>
3830 </listitem>
3831 </varlistentry>
3832
3833 <varlistentry id="protocol-message-formats-AuthenticationMD5Password">
3834 <term>AuthenticationMD5Password (B)</term>
3835 <listitem>
3836 <variablelist>
3837 <varlistentry>
3838 <term>Byte1('R')</term>
3839 <listitem>
3840 <para>
3841 Identifies the message as an authentication request.
3842 </para>
3843 </listitem>
3844 </varlistentry>
3845
3846 <varlistentry>
3847 <term>Int32(12)</term>
3848 <listitem>
3849 <para>
3850 Length of message contents in bytes, including self.
3851 </para>
3852 </listitem>
3853 </varlistentry>
3854
3855 <varlistentry>
3856 <term>Int32(5)</term>
3857 <listitem>
3858 <para>
3859 Specifies that an MD5-encrypted password is required.
3860 </para>
3861 </listitem>
3862 </varlistentry>
3863
3864 <varlistentry>
3865 <term>Byte4</term>
3866 <listitem>
3867 <para>
3868 The salt to use when encrypting the password.
3869 </para>
3870 </listitem>
3871 </varlistentry>
3872 </variablelist>
3873 </listitem>
3874 </varlistentry>
3875
3876 <varlistentry id="protocol-message-formats-AuthenticationGSS">
3877 <term>AuthenticationGSS (B)</term>
3878 <listitem>
3879 <variablelist>
3880 <varlistentry>
3881 <term>Byte1('R')</term>
3882 <listitem>
3883 <para>
3884 Identifies the message as an authentication request.
3885 </para>
3886 </listitem>
3887 </varlistentry>
3888 <varlistentry>
3889 <term>Int32(8)</term>
3890 <listitem>
3891 <para>
3892 Length of message contents in bytes, including self.
3893 </para>
3894 </listitem>
3895 </varlistentry>
3896
3897 <varlistentry>
3898 <term>Int32(7)</term>
3899 <listitem>
3900 <para>
3901 Specifies that GSSAPI authentication is required.
3902 </para>
3903 </listitem>
3904 </varlistentry>
3905 </variablelist>
3906 </listitem>
3907 </varlistentry>
3908
3909 <varlistentry id="protocol-message-formats-AuthenticationGSSContinue">
3910 <term>AuthenticationGSSContinue (B)</term>
3911 <listitem>
3912 <variablelist>
3913 <varlistentry>
3914 <term>Byte1('R')</term>
3915 <listitem>
3916 <para>
3917 Identifies the message as an authentication request.
3918 </para>
3919 </listitem>
3920 </varlistentry>
3921
3922 <varlistentry>
3923 <term>Int32</term>
3924 <listitem>
3925 <para>
3926 Length of message contents in bytes, including self.
3927 </para>
3928 </listitem>
3929 </varlistentry>
3930
3931 <varlistentry>
3932 <term>Int32(8)</term>
3933 <listitem>
3934 <para>
3935 Specifies that this message contains GSSAPI or SSPI data.
3936 </para>
3937 </listitem>
3938 </varlistentry>
3939
3940 <varlistentry>
3941 <term>Byte<replaceable>n</replaceable></term>
3942 <listitem>
3943 <para>
3944 GSSAPI or SSPI authentication data.
3945 </para>
3946 </listitem>
3947 </varlistentry>
3948 </variablelist>
3949 </listitem>
3950 </varlistentry>
3951
3952 <varlistentry id="protocol-message-formats-AuthenticationSSPI">
3953 <term>AuthenticationSSPI (B)</term>
3954 <listitem>
3955 <variablelist>
3956 <varlistentry>
3957 <term>Byte1('R')</term>
3958 <listitem>
3959 <para>
3960 Identifies the message as an authentication request.
3961 </para>
3962 </listitem>
3963 </varlistentry>
3964
3965 <varlistentry>
3966 <term>Int32(8)</term>
3967 <listitem>
3968 <para>
3969 Length of message contents in bytes, including self.
3970 </para>
3971 </listitem>
3972 </varlistentry>
3973
3974 <varlistentry>
3975 <term>Int32(9)</term>
3976 <listitem>
3977 <para>
3978 Specifies that SSPI authentication is required.
3979 </para>
3980 </listitem>
3981 </varlistentry>
3982 </variablelist>
3983 </listitem>
3984 </varlistentry>
3985
3986 <varlistentry id="protocol-message-formats-AuthenticationSASL">
3987 <term>AuthenticationSASL (B)</term>
3988 <listitem>
3989 <variablelist>
3990 <varlistentry>
3991 <term>Byte1('R')</term>
3992 <listitem>
3993 <para>
3994 Identifies the message as an authentication request.
3995 </para>
3996 </listitem>
3997 </varlistentry>
3998
3999 <varlistentry>
4000 <term>Int32</term>
4001 <listitem>
4002 <para>
4003 Length of message contents in bytes, including self.
4004 </para>
4005 </listitem>
4006 </varlistentry>
4007
4008 <varlistentry>
4009 <term>Int32(10)</term>
4010 <listitem>
4011 <para>
4012 Specifies that SASL authentication is required.
4013 </para>
4014 </listitem>
4015 </varlistentry>
4016 </variablelist>
4017
4018 <para>
4019 The message body is a list of SASL authentication mechanisms, in the
4020 server's order of preference. A zero byte is required as terminator after
4021 the last authentication mechanism name. For each mechanism, there is the
4022 following:
4023
4024 <variablelist>
4025 <varlistentry>
4026 <term>String</term>
4027 <listitem>
4028 <para>
4029 Name of a SASL authentication mechanism.
4030 </para>
4031 </listitem>
4032 </varlistentry>
4033 </variablelist>
4034 </para>
4035 </listitem>
4036 </varlistentry>
4037
4038 <varlistentry id="protocol-message-formats-AuthenticationSASLContinue">
4039 <term>AuthenticationSASLContinue (B)</term>
4040 <listitem>
4041 <variablelist>
4042 <varlistentry>
4043 <term>Byte1('R')</term>
4044 <listitem>
4045 <para>
4046 Identifies the message as an authentication request.
4047 </para>
4048 </listitem>
4049 </varlistentry>
4050
4051 <varlistentry>
4052 <term>Int32</term>
4053 <listitem>
4054 <para>
4055 Length of message contents in bytes, including self.
4056 </para>
4057 </listitem>
4058 </varlistentry>
4059
4060 <varlistentry>
4061 <term>Int32(11)</term>
4062 <listitem>
4063 <para>
4064 Specifies that this message contains a SASL challenge.
4065 </para>
4066 </listitem>
4067 </varlistentry>
4068
4069 <varlistentry>
4070 <term>Byte<replaceable>n</replaceable></term>
4071 <listitem>
4072 <para>
4073 SASL data, specific to the SASL mechanism being used.
4074 </para>
4075 </listitem>
4076 </varlistentry>
4077 </variablelist>
4078 </listitem>
4079 </varlistentry>
4080
4081 <varlistentry id="protocol-message-formats-AuthenticationSASLFinal">
4082 <term>AuthenticationSASLFinal (B)</term>
4083 <listitem>
4084 <variablelist>
4085 <varlistentry>
4086 <term>Byte1('R')</term>
4087 <listitem>
4088 <para>
4089 Identifies the message as an authentication request.
4090 </para>
4091 </listitem>
4092 </varlistentry>
4093
4094 <varlistentry>
4095 <term>Int32</term>
4096 <listitem>
4097 <para>
4098 Length of message contents in bytes, including self.
4099 </para>
4100 </listitem>
4101 </varlistentry>
4102
4103 <varlistentry>
4104 <term>Int32(12)</term>
4105 <listitem>
4106 <para>
4107 Specifies that SASL authentication has completed.
4108 </para>
4109 </listitem>
4110 </varlistentry>
4111
4112 <varlistentry>
4113 <term>Byte<replaceable>n</replaceable></term>
4114 <listitem>
4115 <para>
4116 SASL outcome "additional data", specific to the SASL mechanism
4117 being used.
4118 </para>
4119 </listitem>
4120 </varlistentry>
4121 </variablelist>
4122 </listitem>
4123 </varlistentry>
4124
4125 <varlistentry id="protocol-message-formats-BackendKeyData">
4126 <term>BackendKeyData (B)</term>
4127 <listitem>
4128 <variablelist>
4129 <varlistentry>
4130 <term>Byte1('K')</term>
4131 <listitem>
4132 <para>
4133 Identifies the message as cancellation key data.
4134 The frontend must save these values if it wishes to be
4135 able to issue CancelRequest messages later.
4136 </para>
4137 </listitem>
4138 </varlistentry>
4139
4140 <varlistentry>
4141 <term>Int32</term>
4142 <listitem>
4143 <para>
4144 Length of message contents in bytes, including self.
4145 </para>
4146 </listitem>
4147 </varlistentry>
4148
4149 <varlistentry>
4150 <term>Int32</term>
4151 <listitem>
4152 <para>
4153 The process ID of this backend.
4154 </para>
4155 </listitem>
4156 </varlistentry>
4157
4158 <varlistentry>
4159 <term>Byte<replaceable>n</replaceable></term>
4160 <listitem>
4161 <para>
4162 The secret key of this backend. This field extends to the end of the
4163 message, indicated by the length field.
4164 </para>
4165 <para>
4166 The minimum and maximum key length are 4 and 256 bytes, respectively. The
4167 <productname>PostgreSQL</productname> server only sends keys up to
4168 32 bytes, but the larger maximum size allows for future server
4169 versions, as well as connection poolers and other middleware, to use
4170 longer keys. One possible use case is augmenting the server's key
4171 with extra information. Middleware is therefore also encouraged to
4172 not use up all of the bytes, in case multiple middleware
4173 applications are layered on top of each other, each of which may
4174 wrap the key with extra data.
4175 </para>
4176 </listitem>
4177 </varlistentry>
4178 </variablelist>
4179 <para>
4180 Before protocol version 3.2, the secret key was always 4 bytes long.
4181 </para>
4182 </listitem>
4183 </varlistentry>
4184
4185 <varlistentry id="protocol-message-formats-Bind">
4186 <term>Bind (F)</term>
4187 <listitem>
4188 <variablelist>
4189 <varlistentry>
4190 <term>Byte1('B')</term>
4191 <listitem>
4192 <para>
4193 Identifies the message as a Bind command.
4194 </para>
4195 </listitem>
4196 </varlistentry>
4197
4198 <varlistentry>
4199 <term>Int32</term>
4200 <listitem>
4201 <para>
4202 Length of message contents in bytes, including self.
4203 </para>
4204 </listitem>
4205 </varlistentry>
4206
4207 <varlistentry>
4208 <term>String</term>
4209 <listitem>
4210 <para>
4211 The name of the destination portal
4212 (an empty string selects the unnamed portal).
4213 </para>
4214 </listitem>
4215 </varlistentry>
4216
4217 <varlistentry>
4218 <term>String</term>
4219 <listitem>
4220 <para>
4221 The name of the source prepared statement
4222 (an empty string selects the unnamed prepared statement).
4223 </para>
4224 </listitem>
4225 </varlistentry>
4226
4227 <varlistentry>
4228 <term>Int16</term>
4229 <listitem>
4230 <para>
4231 The number of parameter format codes that follow
4232 (denoted <replaceable>C</replaceable> below).
4233 This can be zero to indicate that there are no parameters
4234 or that the parameters all use the default format (text);
4235 or one, in which case the specified format code is applied
4236 to all parameters; or it can equal the actual number of
4237 parameters.
4238 </para>
4239 </listitem>
4240 </varlistentry>
4241
4242 <varlistentry>
4243 <term>Int16[<replaceable>C</replaceable>]</term>
4244 <listitem>
4245 <para>
4246 The parameter format codes. Each must presently be
4247 zero (text) or one (binary).
4248 </para>
4249 </listitem>
4250 </varlistentry>
4251
4252 <varlistentry>
4253 <term>Int16</term>
4254 <listitem>
4255 <para>
4256 The number of parameter values that follow (possibly zero).
4257 This must match the number of parameters needed by the query.
4258 </para>
4259 </listitem>
4260 </varlistentry>
4261 </variablelist>
4262
4263 <para>
4264 Next, the following pair of fields appear for each parameter:
4265 </para>
4266
4267 <variablelist>
4268 <varlistentry>
4269 <term>Int32</term>
4270 <listitem>
4271 <para>
4272 The length of the parameter value, in bytes (this count
4273 does not include itself). Can be zero.
4274 As a special case, -1 indicates a NULL parameter value.
4275 No value bytes follow in the NULL case.
4276 </para>
4277 </listitem>
4278 </varlistentry>
4279
4280 <varlistentry>
4281 <term>Byte<replaceable>n</replaceable></term>
4282 <listitem>
4283 <para>
4284 The value of the parameter, in the format indicated by the
4285 associated format code.
4286 <replaceable>n</replaceable> is the above length.
4287 </para>
4288 </listitem>
4289 </varlistentry>
4290 </variablelist>
4291
4292 <para>
4293 After the last parameter, the following fields appear:
4294 </para>
4295
4296 <variablelist>
4297 <varlistentry>
4298 <term>Int16</term>
4299 <listitem>
4300 <para>
4301 The number of result-column format codes that follow
4302 (denoted <replaceable>R</replaceable> below).
4303 This can be zero to indicate that there are no result columns
4304 or that the result columns should all use the default format
4305 (text);
4306 or one, in which case the specified format code is applied
4307 to all result columns (if any); or it can equal the actual
4308 number of result columns of the query.
4309 </para>
4310 </listitem>
4311 </varlistentry>
4312
4313 <varlistentry>
4314 <term>Int16[<replaceable>R</replaceable>]</term>
4315 <listitem>
4316 <para>
4317 The result-column format codes. Each must presently be
4318 zero (text) or one (binary).
4319 </para>
4320 </listitem>
4321 </varlistentry>
4322 </variablelist>
4323 </listitem>
4324 </varlistentry>
4325
4326 <varlistentry id="protocol-message-formats-BindComplete">
4327 <term>BindComplete (B)</term>
4328 <listitem>
4329 <variablelist>
4330 <varlistentry>
4331 <term>Byte1('2')</term>
4332 <listitem>
4333 <para>
4334 Identifies the message as a Bind-complete indicator.
4335 </para>
4336 </listitem>
4337 </varlistentry>
4338
4339 <varlistentry>
4340 <term>Int32(4)</term>
4341 <listitem>
4342 <para>
4343 Length of message contents in bytes, including self.
4344 </para>
4345 </listitem>
4346 </varlistentry>
4347
4348 </variablelist>
4349 </listitem>
4350 </varlistentry>
4351
4352 <varlistentry id="protocol-message-formats-CancelRequest">
4353 <term>CancelRequest (F)</term>
4354 <listitem>
4355 <variablelist>
4356 <varlistentry>
4357 <term>Int32</term>
4358 <listitem>
4359 <para>
4360 Length of message contents in bytes, including self.
4361 </para>
4362 </listitem>
4363 </varlistentry>
4364
4365 <varlistentry>
4366 <term>Int32(80877102)</term>
4367 <listitem>
4368 <para>
4369 The cancel request code. The value is chosen to contain
4370 <literal>1234</literal> in the most significant 16 bits, and <literal>5678</literal> in the
4371 least significant 16 bits. (To avoid confusion, this code
4372 must not be the same as any protocol version number.)
4373 </para>
4374 </listitem>
4375 </varlistentry>
4376
4377 <varlistentry>
4378 <term>Int32</term>
4379 <listitem>
4380 <para>
4381 The process ID of the target backend.
4382 </para>
4383 </listitem>
4384 </varlistentry>
4385
4386 <varlistentry>
4387 <term>Byte<replaceable>n</replaceable></term>
4388 <listitem>
4389 <para>
4390 The secret key for the target backend. This field extends to the end of the
4391 message, indicated by the length field. The maximum key length is 256 bytes.
4392 </para>
4393 </listitem>
4394 </varlistentry>
4395 </variablelist>
4396 <para>
4397 Before protocol version 3.2, the secret key was always 4 bytes long.
4398 </para>
4399 </listitem>
4400 </varlistentry>
4401
4402 <varlistentry id="protocol-message-formats-Close">
4403 <term>Close (F)</term>
4404 <listitem>
4405 <variablelist>
4406 <varlistentry>
4407 <term>Byte1('C')</term>
4408 <listitem>
4409 <para>
4410 Identifies the message as a Close command.
4411 </para>
4412 </listitem>
4413 </varlistentry>
4414
4415 <varlistentry>
4416 <term>Int32</term>
4417 <listitem>
4418 <para>
4419 Length of message contents in bytes, including self.
4420 </para>
4421 </listitem>
4422 </varlistentry>
4423
4424 <varlistentry>
4425 <term>Byte1</term>
4426 <listitem>
4427 <para>
4428 '<literal>S</literal>' to close a prepared statement; or
4429 '<literal>P</literal>' to close a portal.
4430 </para>
4431 </listitem>
4432 </varlistentry>
4433
4434 <varlistentry>
4435 <term>String</term>
4436 <listitem>
4437 <para>
4438 The name of the prepared statement or portal to close
4439 (an empty string selects the unnamed prepared statement
4440 or portal).
4441 </para>
4442 </listitem>
4443 </varlistentry>
4444 </variablelist>
4445 </listitem>
4446 </varlistentry>
4447
4448 <varlistentry id="protocol-message-formats-CloseComplete">
4449 <term>CloseComplete (B)</term>
4450 <listitem>
4451 <variablelist>
4452 <varlistentry>
4453 <term>Byte1('3')</term>
4454 <listitem>
4455 <para>
4456 Identifies the message as a Close-complete indicator.
4457 </para>
4458 </listitem>
4459 </varlistentry>
4460
4461 <varlistentry>
4462 <term>Int32(4)</term>
4463 <listitem>
4464 <para>
4465 Length of message contents in bytes, including self.
4466 </para>
4467 </listitem>
4468 </varlistentry>
4469 </variablelist>
4470 </listitem>
4471 </varlistentry>
4472
4473 <varlistentry id="protocol-message-formats-CommandComplete">
4474 <term>CommandComplete (B)</term>
4475 <listitem>
4476 <variablelist>
4477 <varlistentry>
4478 <term>Byte1('C')</term>
4479 <listitem>
4480 <para>
4481 Identifies the message as a command-completed response.
4482 </para>
4483 </listitem>
4484 </varlistentry>
4485
4486 <varlistentry>
4487 <term>Int32</term>
4488 <listitem>
4489 <para>
4490 Length of message contents in bytes, including self.
4491 </para>
4492 </listitem>
4493 </varlistentry>
4494
4495 <varlistentry>
4496 <term>String</term>
4497 <listitem>
4498 <para>
4499 The command tag. This is usually a single
4500 word that identifies which SQL command was completed.
4501 </para>
4502
4503 <para>
4504 For an <command>INSERT</command> command, the tag is
4505 <literal>INSERT <replaceable>oid</replaceable>
4506 <replaceable>rows</replaceable></literal>, where
4507 <replaceable>rows</replaceable> is the number of rows
4508 inserted. <replaceable>oid</replaceable> used to be the object ID
4509 of the inserted row if <replaceable>rows</replaceable> was 1
4510 and the target table had OIDs, but OIDs system columns are
4511 not supported anymore; therefore <replaceable>oid</replaceable>
4512 is always 0.
4513 </para>
4514
4515 <para>
4516 For a <command>DELETE</command> command, the tag is
4517 <literal>DELETE <replaceable>rows</replaceable></literal> where
4518 <replaceable>rows</replaceable> is the number of rows deleted.
4519 </para>
4520
4521 <para>
4522 For an <command>UPDATE</command> command, the tag is
4523 <literal>UPDATE <replaceable>rows</replaceable></literal> where
4524 <replaceable>rows</replaceable> is the number of rows updated.
4525 </para>
4526
4527 <para>
4528 For a <command>MERGE</command> command, the tag is
4529 <literal>MERGE <replaceable>rows</replaceable></literal> where
4530 <replaceable>rows</replaceable> is the number of rows inserted,
4531 updated, or deleted.
4532 </para>
4533
4534 <para>
4535 For a <command>SELECT</command> or <command>CREATE TABLE AS</command>
4536 command, the tag is <literal>SELECT <replaceable>rows</replaceable></literal>
4537 where <replaceable>rows</replaceable> is the number of rows retrieved.
4538 </para>
4539
4540 <para>
4541 For a <command>MOVE</command> command, the tag is
4542 <literal>MOVE <replaceable>rows</replaceable></literal> where
4543 <replaceable>rows</replaceable> is the number of rows the
4544 cursor's position has been changed by.
4545 </para>
4546
4547 <para>
4548 For a <command>FETCH</command> command, the tag is
4549 <literal>FETCH <replaceable>rows</replaceable></literal> where
4550 <replaceable>rows</replaceable> is the number of rows that
4551 have been retrieved from the cursor.
4552 </para>
4553
4554 <para>
4555 For a <command>COPY</command> command, the tag is
4556 <literal>COPY <replaceable>rows</replaceable></literal> where
4557 <replaceable>rows</replaceable> is the number of rows copied.
4558 (Note: the row count appears only in
4559 <productname>PostgreSQL</productname> 8.2 and later.)
4560 </para>
4561 </listitem>
4562 </varlistentry>
4563 </variablelist>
4564 </listitem>
4565 </varlistentry>
4566
4567 <varlistentry id="protocol-message-formats-CopyData">
4568 <term>CopyData (F &amp; B)</term>
4569 <listitem>
4570 <variablelist>
4571 <varlistentry>
4572 <term>Byte1('d')</term>
4573 <listitem>
4574 <para>
4575 Identifies the message as <command>COPY</command> data.
4576 </para>
4577 </listitem>
4578 </varlistentry>
4579
4580 <varlistentry>
4581 <term>Int32</term>
4582 <listitem>
4583 <para>
4584 Length of message contents in bytes, including self.
4585 </para>
4586 </listitem>
4587 </varlistentry>
4588
4589 <varlistentry>
4590 <term>Byte<replaceable>n</replaceable></term>
4591 <listitem>
4592 <para>
4593 Data that forms part of a <command>COPY</command> data stream. Messages sent
4594 from the backend will always correspond to single data rows,
4595 but messages sent by frontends might divide the data stream
4596 arbitrarily.
4597 </para>
4598 </listitem>
4599 </varlistentry>
4600 </variablelist>
4601 </listitem>
4602 </varlistentry>
4603
4604 <varlistentry id="protocol-message-formats-CopyDone">
4605 <term>CopyDone (F &amp; B)</term>
4606 <listitem>
4607 <variablelist>
4608 <varlistentry>
4609 <term>Byte1('c')</term>
4610 <listitem>
4611 <para>
4612 Identifies the message as a <command>COPY</command>-complete indicator.
4613 </para>
4614 </listitem>
4615 </varlistentry>
4616
4617 <varlistentry>
4618 <term>Int32(4)</term>
4619 <listitem>
4620 <para>
4621 Length of message contents in bytes, including self.
4622 </para>
4623 </listitem>
4624 </varlistentry>
4625 </variablelist>
4626 </listitem>
4627 </varlistentry>
4628
4629 <varlistentry id="protocol-message-formats-CopyFail">
4630 <term>CopyFail (F)</term>
4631 <listitem>
4632 <variablelist>
4633 <varlistentry>
4634 <term>Byte1('f')</term>
4635 <listitem>
4636 <para>
4637 Identifies the message as a <command>COPY</command>-failure indicator.
4638 </para>
4639 </listitem>
4640 </varlistentry>
4641 <varlistentry>
4642 <term>Int32</term>
4643 <listitem>
4644 <para>
4645 Length of message contents in bytes, including self.
4646 </para>
4647 </listitem>
4648 </varlistentry>
4649
4650 <varlistentry>
4651 <term>String</term>
4652 <listitem>
4653 <para>
4654 An error message to report as the cause of failure.
4655 </para>
4656 </listitem>
4657 </varlistentry>
4658 </variablelist>
4659 </listitem>
4660 </varlistentry>
4661
4662 <varlistentry id="protocol-message-formats-CopyInResponse">
4663 <term>CopyInResponse (B)</term>
4664 <listitem>
4665 <variablelist>
4666 <varlistentry>
4667 <term>Byte1('G')</term>
4668 <listitem>
4669 <para>
4670 Identifies the message as a Start Copy In response.
4671 The frontend must now send copy-in data (if not
4672 prepared to do so, send a CopyFail message).
4673 </para>
4674 </listitem>
4675 </varlistentry>
4676
4677 <varlistentry>
4678 <term>Int32</term>
4679 <listitem>
4680 <para>
4681 Length of message contents in bytes, including self.
4682 </para>
4683 </listitem>
4684 </varlistentry>
4685
4686 <varlistentry>
4687 <term>Int8</term>
4688 <listitem>
4689 <para>
4690 0 indicates the overall <command>COPY</command> format is textual (rows
4691 separated by newlines, columns separated by separator
4692 characters, etc.).
4693 1 indicates the overall copy format is binary (similar
4694 to DataRow format).
4695 See <xref linkend="sql-copy"/>
4696 for more information.
4697 </para>
4698 </listitem>
4699 </varlistentry>
4700
4701 <varlistentry>
4702 <term>Int16</term>
4703 <listitem>
4704 <para>
4705 The number of columns in the data to be copied
4706 (denoted <replaceable>N</replaceable> below).
4707 </para>
4708 </listitem>
4709 </varlistentry>
4710
4711 <varlistentry>
4712 <term>Int16[<replaceable>N</replaceable>]</term>
4713 <listitem>
4714 <para>
4715 The format codes to be used for each column.
4716 Each must presently be zero (text) or one (binary).
4717 All must be zero if the overall copy format is textual.
4718 </para>
4719 </listitem>
4720 </varlistentry>
4721 </variablelist>
4722 </listitem>
4723 </varlistentry>
4724
4725 <varlistentry id="protocol-message-formats-CopyOutResponse">
4726 <term>CopyOutResponse (B)</term>
4727 <listitem>
4728 <variablelist>
4729 <varlistentry>
4730 <term>Byte1('H')</term>
4731 <listitem>
4732 <para>
4733 Identifies the message as a Start Copy Out response.
4734 This message will be followed by copy-out data.
4735 </para>
4736 </listitem>
4737 </varlistentry>
4738
4739 <varlistentry>
4740 <term>Int32</term>
4741 <listitem>
4742 <para>
4743 Length of message contents in bytes, including self.
4744 </para>
4745 </listitem>
4746 </varlistentry>
4747
4748 <varlistentry>
4749 <term>Int8</term>
4750 <listitem>
4751 <para>
4752 0 indicates the overall <command>COPY</command> format
4753 is textual (rows separated by newlines, columns
4754 separated by separator characters, etc.). 1 indicates
4755 the overall copy format is binary (similar to DataRow
4756 format). See <xref linkend="sql-copy"/> for more information.
4757 </para>
4758 </listitem>
4759 </varlistentry>
4760
4761 <varlistentry>
4762 <term>Int16</term>
4763 <listitem>
4764 <para>
4765 The number of columns in the data to be copied
4766 (denoted <replaceable>N</replaceable> below).
4767 </para>
4768 </listitem>
4769 </varlistentry>
4770
4771 <varlistentry>
4772 <term>Int16[<replaceable>N</replaceable>]</term>
4773 <listitem>
4774 <para>
4775 The format codes to be used for each column.
4776 Each must presently be zero (text) or one (binary).
4777 All must be zero if the overall copy format is textual.
4778 </para>
4779 </listitem>
4780 </varlistentry>
4781 </variablelist>
4782 </listitem>
4783 </varlistentry>
4784
4785 <varlistentry id="protocol-message-formats-CopyBothResponse">
4786 <term>CopyBothResponse (B)</term>
4787 <listitem>
4788 <variablelist>
4789 <varlistentry>
4790 <term>Byte1('W')</term>
4791 <listitem>
4792 <para>
4793 Identifies the message as a Start Copy Both response.
4794 This message is used only for Streaming Replication.
4795 </para>
4796 </listitem>
4797 </varlistentry>
4798
4799 <varlistentry>
4800 <term>Int32</term>
4801 <listitem>
4802 <para>
4803 Length of message contents in bytes, including self.
4804 </para>
4805 </listitem>
4806 </varlistentry>
4807
4808 <varlistentry>
4809 <term>Int8</term>
4810 <listitem>
4811 <para>
4812 0 indicates the overall <command>COPY</command> format
4813 is textual (rows separated by newlines, columns
4814 separated by separator characters, etc.). 1 indicates
4815 the overall copy format is binary (similar to DataRow
4816 format). See <xref linkend="sql-copy"/> for more information.
4817 </para>
4818 </listitem>
4819 </varlistentry>
4820
4821 <varlistentry>
4822 <term>Int16</term>
4823 <listitem>
4824 <para>
4825 The number of columns in the data to be copied
4826 (denoted <replaceable>N</replaceable> below).
4827 </para>
4828 </listitem>
4829 </varlistentry>
4830
4831 <varlistentry>
4832 <term>Int16[<replaceable>N</replaceable>]</term>
4833 <listitem>
4834 <para>
4835 The format codes to be used for each column.
4836 Each must presently be zero (text) or one (binary).
4837 All must be zero if the overall copy format is textual.
4838 </para>
4839 </listitem>
4840 </varlistentry>
4841 </variablelist>
4842 </listitem>
4843 </varlistentry>
4844
4845 <varlistentry id="protocol-message-formats-DataRow">
4846 <term>DataRow (B)</term>
4847 <listitem>
4848 <variablelist>
4849 <varlistentry>
4850 <term>Byte1('D')</term>
4851 <listitem>
4852 <para>
4853 Identifies the message as a data row.
4854 </para>
4855 </listitem>
4856 </varlistentry>
4857
4858 <varlistentry>
4859 <term>Int32</term>
4860 <listitem>
4861 <para>
4862 Length of message contents in bytes, including self.
4863 </para>
4864 </listitem>
4865 </varlistentry>
4866
4867 <varlistentry>
4868 <term>Int16</term>
4869 <listitem>
4870 <para>
4871 The number of column values that follow (possibly zero).
4872 </para>
4873 </listitem>
4874 </varlistentry>
4875 </variablelist>
4876
4877 <para>
4878 Next, the following pair of fields appear for each column:
4879 </para>
4880
4881 <variablelist>
4882 <varlistentry>
4883 <term>Int32</term>
4884 <listitem>
4885 <para>
4886 The length of the column value, in bytes (this count
4887 does not include itself). Can be zero.
4888 As a special case, -1 indicates a NULL column value.
4889 No value bytes follow in the NULL case.
4890 </para>
4891 </listitem>
4892 </varlistentry>
4893
4894 <varlistentry>
4895 <term>Byte<replaceable>n</replaceable></term>
4896 <listitem>
4897 <para>
4898 The value of the column, in the format indicated by the
4899 associated format code.
4900 <replaceable>n</replaceable> is the above length.
4901 </para>
4902 </listitem>
4903 </varlistentry>
4904 </variablelist>
4905 </listitem>
4906 </varlistentry>
4907
4908 <varlistentry id="protocol-message-formats-Describe">
4909 <term>Describe (F)</term>
4910 <listitem>
4911 <variablelist>
4912 <varlistentry>
4913 <term>Byte1('D')</term>
4914 <listitem>
4915 <para>
4916 Identifies the message as a Describe command.
4917 </para>
4918 </listitem>
4919 </varlistentry>
4920
4921 <varlistentry>
4922 <term>Int32</term>
4923 <listitem>
4924 <para>
4925 Length of message contents in bytes, including self.
4926 </para>
4927 </listitem>
4928 </varlistentry>
4929
4930 <varlistentry>
4931 <term>Byte1</term>
4932 <listitem>
4933 <para>
4934 '<literal>S</literal>' to describe a prepared statement; or
4935 '<literal>P</literal>' to describe a portal.
4936 </para>
4937 </listitem>
4938 </varlistentry>
4939
4940 <varlistentry>
4941 <term>String</term>
4942 <listitem>
4943 <para>
4944 The name of the prepared statement or portal to describe
4945 (an empty string selects the unnamed prepared statement
4946 or portal).
4947 </para>
4948 </listitem>
4949 </varlistentry>
4950 </variablelist>
4951 </listitem>
4952 </varlistentry>
4953
4954 <varlistentry id="protocol-message-formats-EmptyQueryResponse">
4955 <term>EmptyQueryResponse (B)</term>
4956 <listitem>
4957 <variablelist>
4958 <varlistentry>
4959 <term>Byte1('I')</term>
4960 <listitem>
4961 <para>
4962 Identifies the message as a response to an empty query string.
4963 (This substitutes for CommandComplete.)
4964 </para>
4965 </listitem>
4966 </varlistentry>
4967
4968 <varlistentry>
4969 <term>Int32(4)</term>
4970 <listitem>
4971 <para>
4972 Length of message contents in bytes, including self.
4973 </para>
4974 </listitem>
4975 </varlistentry>
4976 </variablelist>
4977 </listitem>
4978 </varlistentry>
4979
4980 <varlistentry id="protocol-message-formats-ErrorResponse">
4981 <term>ErrorResponse (B)</term>
4982 <listitem>
4983 <variablelist>
4984 <varlistentry>
4985 <term>Byte1('E')</term>
4986 <listitem>
4987 <para>
4988 Identifies the message as an error.
4989 </para>
4990 </listitem>
4991 </varlistentry>
4992
4993 <varlistentry>
4994 <term>Int32</term>
4995 <listitem>
4996 <para>
4997 Length of message contents in bytes, including self.
4998 </para>
4999 </listitem>
5000 </varlistentry>
5001 </variablelist>
5002
5003 <para>
5004 The message body consists of one or more identified fields,
5005 followed by a zero byte as a terminator. Fields can appear in
5006 any order. For each field there is the following:
5007 </para>
5008
5009 <variablelist>
5010 <varlistentry>
5011 <term>Byte1</term>
5012 <listitem>
5013 <para>
5014 A code identifying the field type; if zero, this is
5015 the message terminator and no string follows.
5016 The presently defined field types are listed in
5017 <xref linkend="protocol-error-fields"/>.
5018 Since more field types might be added in future,
5019 frontends should silently ignore fields of unrecognized
5020 type.
5021 </para>
5022 </listitem>
5023 </varlistentry>
5024
5025 <varlistentry>
5026 <term>String</term>
5027 <listitem>
5028 <para>
5029 The field value.
5030 </para>
5031 </listitem>
5032 </varlistentry>
5033 </variablelist>
5034 </listitem>
5035 </varlistentry>
5036
5037 <varlistentry id="protocol-message-formats-Execute">
5038 <term>Execute (F)</term>
5039 <listitem>
5040 <variablelist>
5041 <varlistentry>
5042 <term>Byte1('E')</term>
5043 <listitem>
5044 <para>
5045 Identifies the message as an Execute command.
5046 </para>
5047 </listitem>
5048 </varlistentry>
5049
5050 <varlistentry>
5051 <term>Int32</term>
5052 <listitem>
5053 <para>
5054 Length of message contents in bytes, including self.
5055 </para>
5056 </listitem>
5057 </varlistentry>
5058
5059 <varlistentry>
5060 <term>String</term>
5061 <listitem>
5062 <para>
5063 The name of the portal to execute
5064 (an empty string selects the unnamed portal).
5065 </para>
5066 </listitem>
5067 </varlistentry>
5068
5069 <varlistentry>
5070 <term>Int32</term>
5071 <listitem>
5072 <para>
5073 Maximum number of rows to return, if portal contains
5074 a query that returns rows (ignored otherwise). Zero
5075 denotes <quote>no limit</quote>.
5076 </para>
5077 </listitem>
5078 </varlistentry>
5079 </variablelist>
5080 </listitem>
5081 </varlistentry>
5082
5083 <varlistentry id="protocol-message-formats-Flush">
5084 <term>Flush (F)</term>
5085 <listitem>
5086 <variablelist>
5087 <varlistentry>
5088 <term>Byte1('H')</term>
5089 <listitem>
5090 <para>
5091 Identifies the message as a Flush command.
5092 </para>
5093 </listitem>
5094 </varlistentry>
5095
5096 <varlistentry>
5097 <term>Int32(4)</term>
5098 <listitem>
5099 <para>
5100 Length of message contents in bytes, including self.
5101 </para>
5102 </listitem>
5103 </varlistentry>
5104 </variablelist>
5105 </listitem>
5106 </varlistentry>
5107
5108 <varlistentry id="protocol-message-formats-FunctionCall">
5109 <term>FunctionCall (F)</term>
5110 <listitem>
5111 <variablelist>
5112 <varlistentry>
5113 <term>Byte1('F')</term>
5114 <listitem>
5115 <para>
5116 Identifies the message as a function call.
5117 </para>
5118 </listitem>
5119 </varlistentry>
5120
5121 <varlistentry>
5122 <term>Int32</term>
5123 <listitem>
5124 <para>
5125 Length of message contents in bytes, including self.
5126 </para>
5127 </listitem>
5128 </varlistentry>
5129
5130 <varlistentry>
5131 <term>Int32</term>
5132 <listitem>
5133 <para>
5134 Specifies the object ID of the function to call.
5135 </para>
5136 </listitem>
5137 </varlistentry>
5138
5139 <varlistentry>
5140 <term>Int16</term>
5141 <listitem>
5142 <para>
5143 The number of argument format codes that follow
5144 (denoted <replaceable>C</replaceable> below).
5145 This can be zero to indicate that there are no arguments
5146 or that the arguments all use the default format (text);
5147 or one, in which case the specified format code is applied
5148 to all arguments; or it can equal the actual number of
5149 arguments.
5150 </para>
5151 </listitem>
5152 </varlistentry>
5153
5154 <varlistentry>
5155 <term>Int16[<replaceable>C</replaceable>]</term>
5156 <listitem>
5157 <para>
5158 The argument format codes. Each must presently be
5159 zero (text) or one (binary).
5160 </para>
5161 </listitem>
5162 </varlistentry>
5163
5164 <varlistentry>
5165 <term>Int16</term>
5166 <listitem>
5167 <para>
5168 Specifies the number of arguments being supplied to the
5169 function.
5170 </para>
5171 </listitem>
5172 </varlistentry>
5173 </variablelist>
5174
5175 <para>
5176 Next, the following pair of fields appear for each argument:
5177 </para>
5178
5179 <variablelist>
5180 <varlistentry>
5181 <term>Int32</term>
5182 <listitem>
5183 <para>
5184 The length of the argument value, in bytes (this count
5185 does not include itself). Can be zero.
5186 As a special case, -1 indicates a NULL argument value.
5187 No value bytes follow in the NULL case.
5188 </para>
5189 </listitem>
5190 </varlistentry>
5191
5192 <varlistentry>
5193 <term>Byte<replaceable>n</replaceable></term>
5194 <listitem>
5195 <para>
5196 The value of the argument, in the format indicated by the
5197 associated format code.
5198 <replaceable>n</replaceable> is the above length.
5199 </para>
5200 </listitem>
5201 </varlistentry>
5202 </variablelist>
5203
5204 <para>
5205 After the last argument, the following field appears:
5206 </para>
5207
5208 <variablelist>
5209 <varlistentry>
5210 <term>Int16</term>
5211 <listitem>
5212 <para>
5213 The format code for the function result. Must presently be
5214 zero (text) or one (binary).
5215 </para>
5216 </listitem>
5217 </varlistentry>
5218 </variablelist>
5219 </listitem>
5220 </varlistentry>
5221
5222 <varlistentry id="protocol-message-formats-FunctionCallResponse">
5223 <term>FunctionCallResponse (B)</term>
5224 <listitem>
5225 <variablelist>
5226 <varlistentry>
5227 <term>Byte1('V')</term>
5228 <listitem>
5229 <para>
5230 Identifies the message as a function call result.
5231 </para>
5232 </listitem>
5233 </varlistentry>
5234
5235 <varlistentry>
5236 <term>Int32</term>
5237 <listitem>
5238 <para>
5239 Length of message contents in bytes, including self.
5240 </para>
5241 </listitem>
5242 </varlistentry>
5243
5244 <varlistentry>
5245 <term>Int32</term>
5246 <listitem>
5247 <para>
5248 The length of the function result value, in bytes (this count
5249 does not include itself). Can be zero.
5250 As a special case, -1 indicates a NULL function result.
5251 No value bytes follow in the NULL case.
5252 </para>
5253 </listitem>
5254 </varlistentry>
5255
5256 <varlistentry>
5257 <term>Byte<replaceable>n</replaceable></term>
5258 <listitem>
5259 <para>
5260 The value of the function result, in the format indicated by
5261 the associated format code.
5262 <replaceable>n</replaceable> is the above length.
5263 </para>
5264 </listitem>
5265 </varlistentry>
5266 </variablelist>
5267 </listitem>
5268 </varlistentry>
5269
5270 <varlistentry id="protocol-message-formats-GSSENCRequest">
5271 <term>GSSENCRequest (F)</term>
5272 <listitem>
5273 <variablelist>
5274 <varlistentry>
5275 <term>Int32(8)</term>
5276 <listitem>
5277 <para>
5278 Length of message contents in bytes, including self.
5279 </para>
5280 </listitem>
5281 </varlistentry>
5282
5283 <varlistentry>
5284 <term>Int32(80877104)</term>
5285 <listitem>
5286 <para>
5287 The <acronym>GSSAPI</acronym> Encryption request code. The value is chosen to contain
5288 <literal>1234</literal> in the most significant 16 bits, and <literal>5680</literal> in the
5289 least significant 16 bits. (To avoid confusion, this code
5290 must not be the same as any protocol version number.)
5291 </para>
5292 </listitem>
5293 </varlistentry>
5294 </variablelist>
5295 </listitem>
5296 </varlistentry>
5297
5298 <varlistentry id="protocol-message-formats-GSSResponse">
5299 <term>GSSResponse (F)</term>
5300 <listitem>
5301 <variablelist>
5302 <varlistentry>
5303 <term>Byte1('p')</term>
5304 <listitem>
5305 <para>
5306 Identifies the message as a GSSAPI or SSPI response. Note that
5307 this is also used for SASL and password response messages.
5308 The exact message type can be deduced from the context.
5309 </para>
5310 </listitem>
5311 </varlistentry>
5312
5313 <varlistentry>
5314 <term>Int32</term>
5315 <listitem>
5316 <para>
5317 Length of message contents in bytes, including self.
5318 </para>
5319 </listitem>
5320 </varlistentry>
5321
5322 <varlistentry>
5323 <term>Byte<replaceable>n</replaceable></term>
5324 <listitem>
5325 <para>
5326 GSSAPI/SSPI specific message data.
5327 </para>
5328 </listitem>
5329 </varlistentry>
5330 </variablelist>
5331 </listitem>
5332 </varlistentry>
5333
5334 <varlistentry id="protocol-message-formats-NegotiateProtocolVersion">
5335 <term>NegotiateProtocolVersion (B)</term>
5336 <listitem>
5337 <variablelist>
5338 <varlistentry>
5339 <term>Byte1('v')</term>
5340 <listitem>
5341 <para>
5342 Identifies the message as a protocol version negotiation
5343 message.
5344 </para>
5345 </listitem>
5346 </varlistentry>
5347
5348 <varlistentry>
5349 <term>Int32</term>
5350 <listitem>
5351 <para>
5352 Length of message contents in bytes, including self.
5353 </para>
5354 </listitem>
5355 </varlistentry>
5356
5357 <varlistentry>
5358 <term>Int32</term>
5359 <listitem>
5360 <para>
5361 Newest minor protocol version supported by the server
5362 for the major protocol version requested by the client.
5363 </para>
5364 </listitem>
5365 </varlistentry>
5366
5367 <varlistentry>
5368 <term>Int32</term>
5369 <listitem>
5370 <para>
5371 Number of protocol options not recognized by the server.
5372 </para>
5373 </listitem>
5374 </varlistentry>
5375 </variablelist>
5376
5377 <para>
5378 Then, for protocol option not recognized by the server, there
5379 is the following:
5380 </para>
5381
5382 <variablelist>
5383 <varlistentry>
5384 <term>String</term>
5385 <listitem>
5386 <para>
5387 The option name.
5388 </para>
5389 </listitem>
5390 </varlistentry>
5391 </variablelist>
5392 </listitem>
5393 </varlistentry>
5394
5395 <varlistentry id="protocol-message-formats-NoData">
5396 <term>NoData (B)</term>
5397 <listitem>
5398 <variablelist>
5399 <varlistentry>
5400 <term>Byte1('n')</term>
5401 <listitem>
5402 <para>
5403 Identifies the message as a no-data indicator.
5404 </para>
5405 </listitem>
5406 </varlistentry>
5407
5408 <varlistentry>
5409 <term>Int32(4)</term>
5410 <listitem>
5411 <para>
5412 Length of message contents in bytes, including self.
5413 </para>
5414 </listitem>
5415 </varlistentry>
5416 </variablelist>
5417 </listitem>
5418 </varlistentry>
5419
5420 <varlistentry id="protocol-message-formats-NoticeResponse">
5421 <term>NoticeResponse (B)</term>
5422 <listitem>
5423 <variablelist>
5424 <varlistentry>
5425 <term>Byte1('N')</term>
5426 <listitem>
5427 <para>
5428 Identifies the message as a notice.
5429 </para>
5430 </listitem>
5431 </varlistentry>
5432
5433 <varlistentry>
5434 <term>Int32</term>
5435 <listitem>
5436 <para>
5437 Length of message contents in bytes, including self.
5438 </para>
5439 </listitem>
5440 </varlistentry>
5441 </variablelist>
5442
5443 <para>
5444 The message body consists of one or more identified fields,
5445 followed by a zero byte as a terminator. Fields can appear in
5446 any order. For each field there is the following:
5447 </para>
5448
5449 <variablelist>
5450 <varlistentry>
5451 <term>Byte1</term>
5452 <listitem>
5453 <para>
5454 A code identifying the field type; if zero, this is
5455 the message terminator and no string follows.
5456 The presently defined field types are listed in
5457 <xref linkend="protocol-error-fields"/>.
5458 Since more field types might be added in future,
5459 frontends should silently ignore fields of unrecognized
5460 type.
5461 </para>
5462 </listitem>
5463 </varlistentry>
5464
5465 <varlistentry>
5466 <term>String</term>
5467 <listitem>
5468 <para>
5469 The field value.
5470 </para>
5471 </listitem>
5472 </varlistentry>
5473 </variablelist>
5474 </listitem>
5475 </varlistentry>
5476
5477 <varlistentry id="protocol-message-formats-NotificationResponse">
5478 <term>NotificationResponse (B)</term>
5479 <listitem>
5480 <variablelist>
5481 <varlistentry>
5482 <term>Byte1('A')</term>
5483 <listitem>
5484 <para>
5485 Identifies the message as a notification response.
5486 </para>
5487 </listitem>
5488 </varlistentry>
5489
5490 <varlistentry>
5491 <term>Int32</term>
5492 <listitem>
5493 <para>
5494 Length of message contents in bytes, including self.
5495 </para>
5496 </listitem>
5497 </varlistentry>
5498
5499 <varlistentry>
5500 <term>Int32</term>
5501 <listitem>
5502 <para>
5503 The process ID of the notifying backend process.
5504 </para>
5505 </listitem>
5506 </varlistentry>
5507
5508 <varlistentry>
5509 <term>String</term>
5510 <listitem>
5511 <para>
5512 The name of the channel that the notify has been raised on.
5513 </para>
5514 </listitem>
5515 </varlistentry>
5516
5517 <varlistentry>
5518 <term>String</term>
5519 <listitem>
5520 <para>
5521 The <quote>payload</quote> string passed from the notifying process.
5522 </para>
5523 </listitem>
5524 </varlistentry>
5525 </variablelist>
5526 </listitem>
5527 </varlistentry>
5528
5529 <varlistentry id="protocol-message-formats-ParameterDescription">
5530 <term>ParameterDescription (B)</term>
5531 <listitem>
5532 <variablelist>
5533 <varlistentry>
5534 <term>Byte1('t')</term>
5535 <listitem>
5536 <para>
5537 Identifies the message as a parameter description.
5538 </para>
5539 </listitem>
5540 </varlistentry>
5541
5542 <varlistentry>
5543 <term>Int32</term>
5544 <listitem>
5545 <para>
5546 Length of message contents in bytes, including self.
5547 </para>
5548 </listitem>
5549 </varlistentry>
5550
5551 <varlistentry>
5552 <term>Int16</term>
5553 <listitem>
5554 <para>
5555 The number of parameters used by the statement
5556 (can be zero).
5557 </para>
5558 </listitem>
5559 </varlistentry>
5560 </variablelist>
5561
5562 <para>
5563 Then, for each parameter, there is the following:
5564 </para>
5565
5566 <variablelist>
5567 <varlistentry>
5568 <term>Int32</term>
5569 <listitem>
5570 <para>
5571 Specifies the object ID of the parameter data type.
5572 </para>
5573 </listitem>
5574 </varlistentry>
5575 </variablelist>
5576 </listitem>
5577 </varlistentry>
5578
5579 <varlistentry id="protocol-message-formats-ParameterStatus">
5580 <term>ParameterStatus (B)</term>
5581 <listitem>
5582 <variablelist>
5583 <varlistentry>
5584 <term>Byte1('S')</term>
5585 <listitem>
5586 <para>
5587 Identifies the message as a run-time parameter status report.
5588 </para>
5589 </listitem>
5590 </varlistentry>
5591
5592 <varlistentry>
5593 <term>Int32</term>
5594 <listitem>
5595 <para>
5596 Length of message contents in bytes, including self.
5597 </para>
5598 </listitem>
5599 </varlistentry>
5600
5601 <varlistentry>
5602 <term>String</term>
5603 <listitem>
5604 <para>
5605 The name of the run-time parameter being reported.
5606 </para>
5607 </listitem>
5608 </varlistentry>
5609
5610 <varlistentry>
5611 <term>String</term>
5612 <listitem>
5613 <para>
5614 The current value of the parameter.
5615 </para>
5616 </listitem>
5617 </varlistentry>
5618 </variablelist>
5619 </listitem>
5620 </varlistentry>
5621
5622 <varlistentry id="protocol-message-formats-Parse">
5623 <term>Parse (F)</term>
5624 <listitem>
5625 <variablelist>
5626 <varlistentry>
5627 <term>Byte1('P')</term>
5628 <listitem>
5629 <para>
5630 Identifies the message as a Parse command.
5631 </para>
5632 </listitem>
5633 </varlistentry>
5634
5635 <varlistentry>
5636 <term>Int32</term>
5637 <listitem>
5638 <para>
5639 Length of message contents in bytes, including self.
5640 </para>
5641 </listitem>
5642 </varlistentry>
5643
5644 <varlistentry>
5645 <term>String</term>
5646 <listitem>
5647 <para>
5648 The name of the destination prepared statement
5649 (an empty string selects the unnamed prepared statement).
5650 </para>
5651 </listitem>
5652 </varlistentry>
5653
5654 <varlistentry>
5655 <term>String</term>
5656 <listitem>
5657 <para>
5658 The query string to be parsed.
5659 </para>
5660 </listitem>
5661 </varlistentry>
5662
5663 <varlistentry>
5664 <term>Int16</term>
5665 <listitem>
5666 <para>
5667 The number of parameter data types specified
5668 (can be zero). Note that this is not an indication of
5669 the number of parameters that might appear in the
5670 query string, only the number that the frontend wants to
5671 prespecify types for.
5672 </para>
5673 </listitem>
5674 </varlistentry>
5675 </variablelist>
5676
5677 <para>
5678 Then, for each parameter, there is the following:
5679 </para>
5680
5681 <variablelist>
5682 <varlistentry>
5683 <term>Int32</term>
5684 <listitem>
5685 <para>
5686 Specifies the object ID of the parameter data type.
5687 Placing a zero here is equivalent to leaving the type
5688 unspecified.
5689 </para>
5690 </listitem>
5691 </varlistentry>
5692 </variablelist>
5693 </listitem>
5694 </varlistentry>
5695
5696 <varlistentry id="protocol-message-formats-ParseComplete">
5697 <term>ParseComplete (B)</term>
5698 <listitem>
5699 <variablelist>
5700 <varlistentry>
5701 <term>Byte1('1')</term>
5702 <listitem>
5703 <para>
5704 Identifies the message as a Parse-complete indicator.
5705 </para>
5706 </listitem>
5707 </varlistentry>
5708
5709 <varlistentry>
5710 <term>Int32(4)</term>
5711 <listitem>
5712 <para>
5713 Length of message contents in bytes, including self.
5714 </para>
5715 </listitem>
5716 </varlistentry>
5717 </variablelist>
5718 </listitem>
5719 </varlistentry>
5720
5721 <varlistentry id="protocol-message-formats-PasswordMessage">
5722 <term>PasswordMessage (F)</term>
5723 <listitem>
5724 <variablelist>
5725 <varlistentry>
5726 <term>Byte1('p')</term>
5727 <listitem>
5728 <para>
5729 Identifies the message as a password response. Note that
5730 this is also used for GSSAPI, SSPI and SASL response messages.
5731 The exact message type can be deduced from the context.
5732 </para>
5733 </listitem>
5734 </varlistentry>
5735
5736 <varlistentry>
5737 <term>Int32</term>
5738 <listitem>
5739 <para>
5740 Length of message contents in bytes, including self.
5741 </para>
5742 </listitem>
5743 </varlistentry>
5744
5745 <varlistentry>
5746 <term>String</term>
5747 <listitem>
5748 <para>
5749 The password (encrypted, if requested).
5750 </para>
5751 </listitem>
5752 </varlistentry>
5753 </variablelist>
5754 </listitem>
5755 </varlistentry>
5756
5757 <varlistentry id="protocol-message-formats-PortalSuspended">
5758 <term>PortalSuspended (B)</term>
5759 <listitem>
5760 <variablelist>
5761 <varlistentry>
5762 <term>Byte1('s')</term>
5763 <listitem>
5764 <para>
5765 Identifies the message as a portal-suspended indicator.
5766 Note this only appears if an Execute message's row-count limit
5767 was reached.
5768 </para>
5769 </listitem>
5770 </varlistentry>
5771
5772 <varlistentry>
5773 <term>Int32(4)</term>
5774 <listitem>
5775 <para>
5776 Length of message contents in bytes, including self.
5777 </para>
5778 </listitem>
5779 </varlistentry>
5780 </variablelist>
5781 </listitem>
5782 </varlistentry>
5783
5784 <varlistentry id="protocol-message-formats-Query">
5785 <term>Query (F)</term>
5786 <listitem>
5787 <variablelist>
5788 <varlistentry>
5789 <term>Byte1('Q')</term>
5790 <listitem>
5791 <para>
5792 Identifies the message as a simple query.
5793 </para>
5794 </listitem>
5795 </varlistentry>
5796
5797 <varlistentry>
5798 <term>Int32</term>
5799 <listitem>
5800 <para>
5801 Length of message contents in bytes, including self.
5802 </para>
5803 </listitem>
5804 </varlistentry>
5805
5806 <varlistentry>
5807 <term>String</term>
5808 <listitem>
5809 <para>
5810 The query string itself.
5811 </para>
5812 </listitem>
5813 </varlistentry>
5814 </variablelist>
5815 </listitem>
5816 </varlistentry>
5817
5818 <varlistentry id="protocol-message-formats-ReadyForQuery">
5819 <term>ReadyForQuery (B)</term>
5820 <listitem>
5821 <variablelist>
5822 <varlistentry>
5823 <term>Byte1('Z')</term>
5824 <listitem>
5825 <para>
5826 Identifies the message type. ReadyForQuery is sent
5827 whenever the backend is ready for a new query cycle.
5828 </para>
5829 </listitem>
5830 </varlistentry>
5831
5832 <varlistentry>
5833 <term>Int32(5)</term>
5834 <listitem>
5835 <para>
5836 Length of message contents in bytes, including self.
5837 </para>
5838 </listitem>
5839 </varlistentry>
5840
5841 <varlistentry>
5842 <term>Byte1</term>
5843 <listitem>
5844 <para>
5845 Current backend transaction status indicator.
5846 Possible values are '<literal>I</literal>' if idle (not in
5847 a transaction block); '<literal>T</literal>' if in a transaction
5848 block; or '<literal>E</literal>' if in a failed transaction
5849 block (queries will be rejected until block is ended).
5850 </para>
5851 </listitem>
5852 </varlistentry>
5853 </variablelist>
5854 </listitem>
5855 </varlistentry>
5856
5857 <varlistentry id="protocol-message-formats-RowDescription">
5858 <term>RowDescription (B)</term>
5859 <listitem>
5860 <variablelist>
5861 <varlistentry>
5862 <term>Byte1('T')</term>
5863 <listitem>
5864 <para>
5865 Identifies the message as a row description.
5866 </para>
5867 </listitem>
5868 </varlistentry>
5869
5870 <varlistentry>
5871 <term>Int32</term>
5872 <listitem>
5873 <para>
5874 Length of message contents in bytes, including self.
5875 </para>
5876 </listitem>
5877 </varlistentry>
5878
5879 <varlistentry>
5880 <term>Int16</term>
5881 <listitem>
5882 <para>
5883 Specifies the number of fields in a row (can be zero).
5884 </para>
5885 </listitem>
5886 </varlistentry>
5887 </variablelist>
5888
5889 <para>
5890 Then, for each field, there is the following:
5891 </para>
5892
5893 <variablelist>
5894 <varlistentry>
5895 <term>String</term>
5896 <listitem>
5897 <para>
5898 The field name.
5899 </para>
5900 </listitem>
5901 </varlistentry>
5902
5903 <varlistentry>
5904 <term>Int32</term>
5905 <listitem>
5906 <para>
5907 If the field can be identified as a column of a specific
5908 table, the object ID of the table; otherwise zero.
5909 </para>
5910 </listitem>
5911 </varlistentry>
5912
5913 <varlistentry>
5914 <term>Int16</term>
5915 <listitem>
5916 <para>
5917 If the field can be identified as a column of a specific
5918 table, the attribute number of the column; otherwise zero.
5919 </para>
5920 </listitem>
5921 </varlistentry>
5922
5923 <varlistentry>
5924 <term>Int32</term>
5925 <listitem>
5926 <para>
5927 The object ID of the field's data type.
5928 </para>
5929 </listitem>
5930 </varlistentry>
5931
5932 <varlistentry>
5933 <term>Int16</term>
5934 <listitem>
5935 <para>
5936 The data type size (see <varname>pg_type.typlen</varname>).
5937 Note that negative values denote variable-width types.
5938 </para>
5939 </listitem>
5940 </varlistentry>
5941
5942 <varlistentry>
5943 <term>Int32</term>
5944 <listitem>
5945 <para>
5946 The type modifier (see <varname>pg_attribute.atttypmod</varname>).
5947 The meaning of the modifier is type-specific.
5948 </para>
5949 </listitem>
5950 </varlistentry>
5951
5952 <varlistentry>
5953 <term>Int16</term>
5954 <listitem>
5955 <para>
5956 The format code being used for the field. Currently will
5957 be zero (text) or one (binary). In a RowDescription
5958 returned from the statement variant of Describe, the
5959 format code is not yet known and will always be zero.
5960 </para>
5961 </listitem>
5962 </varlistentry>
5963 </variablelist>
5964 </listitem>
5965 </varlistentry>
5966
5967 <varlistentry id="protocol-message-formats-SASLInitialResponse">
5968 <term>SASLInitialResponse (F)</term>
5969 <listitem>
5970 <variablelist>
5971 <varlistentry>
5972 <term>Byte1('p')</term>
5973 <listitem>
5974 <para>
5975 Identifies the message as an initial SASL response. Note that
5976 this is also used for GSSAPI, SSPI and password response messages.
5977 The exact message type is deduced from the context.
5978 </para>
5979 </listitem>
5980 </varlistentry>
5981
5982 <varlistentry>
5983 <term>Int32</term>
5984 <listitem>
5985 <para>
5986 Length of message contents in bytes, including self.
5987 </para>
5988 </listitem>
5989 </varlistentry>
5990
5991 <varlistentry>
5992 <term>String</term>
5993 <listitem>
5994 <para>
5995 Name of the SASL authentication mechanism that the client
5996 selected.
5997 </para>
5998 </listitem>
5999 </varlistentry>
6000
6001 <varlistentry>
6002 <term>Int32</term>
6003 <listitem>
6004 <para>
6005 Length of SASL mechanism specific "Initial Client Response" that
6006 follows, or -1 if there is no Initial Response.
6007 </para>
6008 </listitem>
6009 </varlistentry>
6010
6011 <varlistentry>
6012 <term>Byte<replaceable>n</replaceable></term>
6013 <listitem>
6014 <para>
6015 SASL mechanism specific "Initial Response".
6016 </para>
6017 </listitem>
6018 </varlistentry>
6019 </variablelist>
6020 </listitem>
6021 </varlistentry>
6022
6023 <varlistentry id="protocol-message-formats-SASLResponse">
6024 <term>SASLResponse (F)</term>
6025 <listitem>
6026 <variablelist>
6027 <varlistentry>
6028 <term>Byte1('p')</term>
6029 <listitem>
6030 <para>
6031 Identifies the message as a SASL response. Note that
6032 this is also used for GSSAPI, SSPI and password response messages.
6033 The exact message type can be deduced from the context.
6034 </para>
6035 </listitem>
6036 </varlistentry>
6037
6038 <varlistentry>
6039 <term>Int32</term>
6040 <listitem>
6041 <para>
6042 Length of message contents in bytes, including self.
6043 </para>
6044 </listitem>
6045 </varlistentry>
6046
6047 <varlistentry>
6048 <term>Byte<replaceable>n</replaceable></term>
6049 <listitem>
6050 <para>
6051 SASL mechanism specific message data.
6052 </para>
6053 </listitem>
6054 </varlistentry>
6055 </variablelist>
6056 </listitem>
6057 </varlistentry>
6058
6059 <varlistentry id="protocol-message-formats-SSLRequest">
6060 <term>SSLRequest (F)</term>
6061 <listitem>
6062 <variablelist>
6063 <varlistentry>
6064 <term>Int32(8)</term>
6065 <listitem>
6066 <para>
6067 Length of message contents in bytes, including self.
6068 </para>
6069 </listitem>
6070 </varlistentry>
6071
6072 <varlistentry>
6073 <term>Int32(80877103)</term>
6074 <listitem>
6075 <para>
6076 The <acronym>SSL</acronym> request code. The value is chosen to contain
6077 <literal>1234</literal> in the most significant 16 bits, and <literal>5679</literal> in the
6078 least significant 16 bits. (To avoid confusion, this code
6079 must not be the same as any protocol version number.)
6080 </para>
6081 </listitem>
6082 </varlistentry>
6083 </variablelist>
6084 </listitem>
6085 </varlistentry>
6086
6087 <varlistentry id="protocol-message-formats-StartupMessage">
6088 <term>StartupMessage (F)</term>
6089 <listitem>
6090 <variablelist>
6091 <varlistentry>
6092 <term>Int32</term>
6093 <listitem>
6094 <para>
6095 Length of message contents in bytes, including self.
6096 </para>
6097 </listitem>
6098 </varlistentry>
6099
6100 <varlistentry>
6101 <term>Int32(196610)</term>
6102 <listitem>
6103 <para>
6104 The protocol version number. The most significant 16 bits are
6105 the major version number (3 for the protocol described here).
6106 The least significant 16 bits are the minor version number
6107 (2 for the protocol described here).
6108 </para>
6109 </listitem>
6110 </varlistentry>
6111 </variablelist>
6112
6113 <para>
6114 The protocol version number is followed by one or more pairs of
6115 parameter name and value strings. A zero byte is required as a
6116 terminator after the last name/value pair.
6117 Parameters can appear in any
6118 order. <literal>user</literal> is required, others are optional.
6119 Each parameter is specified as:
6120 </para>
6121
6122 <variablelist>
6123 <varlistentry>
6124 <term>String</term>
6125 <listitem>
6126 <para>
6127 The parameter name. Currently recognized names are:
6128
6129 <variablelist>
6130 <varlistentry>
6131 <term><literal>user</literal></term>
6132 <listitem>
6133 <para>
6134 The database user name to connect as. Required;
6135 there is no default.
6136 </para>
6137 </listitem>
6138 </varlistentry>
6139
6140 <varlistentry>
6141 <term><literal>database</literal></term>
6142 <listitem>
6143 <para>
6144 The database to connect to. Defaults to the user name.
6145 </para>
6146 </listitem>
6147 </varlistentry>
6148
6149 <varlistentry>
6150 <term><literal>options</literal></term>
6151 <listitem>
6152 <para>
6153 Command-line arguments for the backend. (This is
6154 deprecated in favor of setting individual run-time
6155 parameters.) Spaces within this string are
6156 considered to separate arguments, unless escaped with
6157 a backslash (<literal>\</literal>); write <literal>\\</literal> to
6158 represent a literal backslash.
6159 </para>
6160 </listitem>
6161 </varlistentry>
6162
6163 <varlistentry>
6164 <term><literal>replication</literal></term>
6165 <listitem>
6166 <para>
6167 Used to connect in streaming replication mode, where
6168 a small set of replication commands can be issued
6169 instead of SQL statements. Value can be
6170 <literal>true</literal>, <literal>false</literal>, or
6171 <literal>database</literal>, and the default is
6172 <literal>false</literal>. See
6173 <xref linkend="protocol-replication"/> for details.
6174 </para>
6175 </listitem>
6176 </varlistentry>
6177 </variablelist>
6178
6179 In addition to the above, other parameters may be listed.
6180 Parameter names beginning with <literal>_pq_.</literal> are
6181 reserved for use as protocol extensions, while others are
6182 treated as run-time parameters to be set at backend start
6183 time. Such settings will be applied during backend start
6184 (after parsing the command-line arguments if any) and will
6185 act as session defaults.
6186 </para>
6187 </listitem>
6188 </varlistentry>
6189
6190 <varlistentry>
6191 <term>String</term>
6192 <listitem>
6193 <para>
6194 The parameter value.
6195 </para>
6196 </listitem>
6197 </varlistentry>
6198 </variablelist>
6199 </listitem>
6200 </varlistentry>
6201
6202 <varlistentry id="protocol-message-formats-Sync">
6203 <term>Sync (F)</term>
6204 <listitem>
6205 <variablelist>
6206 <varlistentry>
6207 <term>Byte1('S')</term>
6208 <listitem>
6209 <para>
6210 Identifies the message as a Sync command.
6211 </para>
6212 </listitem>
6213 </varlistentry>
6214
6215 <varlistentry>
6216 <term>Int32(4)</term>
6217 <listitem>
6218 <para>
6219 Length of message contents in bytes, including self.
6220 </para>
6221 </listitem>
6222 </varlistentry>
6223 </variablelist>
6224 </listitem>
6225 </varlistentry>
6226
6227 <varlistentry id="protocol-message-formats-Terminate">
6228 <term>Terminate (F)</term>
6229 <listitem>
6230 <variablelist>
6231 <varlistentry>
6232 <term>Byte1('X')</term>
6233 <listitem>
6234 <para>
6235 Identifies the message as a termination.
6236 </para>
6237 </listitem>
6238 </varlistentry>
6239
6240 <varlistentry>
6241 <term>Int32(4)</term>
6242 <listitem>
6243 <para>
6244 Length of message contents in bytes, including self.
6245 </para>
6246 </listitem>
6247 </varlistentry>
6248 </variablelist>
6249 </listitem>
6250 </varlistentry>
6251 </variablelist>
6252 </sect1>
6253
6254 <sect1 id="protocol-error-fields">
6255 <title>Error and Notice Message Fields</title>
6256
6257 <para>
6258 This section describes the fields that can appear in ErrorResponse and
6259 NoticeResponse messages. Each field type has a single-byte identification
6260 token. Note that any given field type should appear at most once per
6261 message.
6262 </para>
6263
6264 <variablelist>
6265 <varlistentry>
6266 <term><literal>S</literal></term>
6267 <listitem>
6268 <para>
6269 Severity: the field contents are
6270 <literal>ERROR</literal>, <literal>FATAL</literal>, or
6271 <literal>PANIC</literal> (in an error message), or
6272 <literal>WARNING</literal>, <literal>NOTICE</literal>, <literal>DEBUG</literal>,
6273 <literal>INFO</literal>, or <literal>LOG</literal> (in a notice message),
6274 or a localized translation of one of these. Always present.
6275 </para>
6276 </listitem>
6277 </varlistentry>
6278
6279 <varlistentry>
6280 <term><literal>V</literal></term>
6281 <listitem>
6282 <para>
6283 Severity: the field contents are
6284 <literal>ERROR</literal>, <literal>FATAL</literal>, or
6285 <literal>PANIC</literal> (in an error message), or
6286 <literal>WARNING</literal>, <literal>NOTICE</literal>, <literal>DEBUG</literal>,
6287 <literal>INFO</literal>, or <literal>LOG</literal> (in a notice message).
6288 This is identical to the <literal>S</literal> field except
6289 that the contents are never localized. This is present only in
6290 messages generated by <productname>PostgreSQL</productname> versions 9.6
6291 and later.
6292 </para>
6293 </listitem>
6294 </varlistentry>
6295
6296 <varlistentry>
6297 <term><literal>C</literal></term>
6298 <listitem>
6299 <para>
6300 Code: the SQLSTATE code for the error (see <xref
6301 linkend="errcodes-appendix"/>). Not localizable. Always present.
6302 </para>
6303 </listitem>
6304 </varlistentry>
6305
6306 <varlistentry>
6307 <term><literal>M</literal></term>
6308 <listitem>
6309 <para>
6310 Message: the primary human-readable error message.
6311 This should be accurate but terse (typically one line).
6312 Always present.
6313 </para>
6314 </listitem>
6315 </varlistentry>
6316
6317 <varlistentry>
6318 <term><literal>D</literal></term>
6319 <listitem>
6320 <para>
6321 Detail: an optional secondary error message carrying more
6322 detail about the problem. Might run to multiple lines.
6323 </para>
6324 </listitem>
6325 </varlistentry>
6326
6327 <varlistentry>
6328 <term><literal>H</literal></term>
6329 <listitem>
6330 <para>
6331 Hint: an optional suggestion what to do about the problem.
6332 This is intended to differ from Detail in that it offers advice
6333 (potentially inappropriate) rather than hard facts.
6334 Might run to multiple lines.
6335 </para>
6336 </listitem>
6337 </varlistentry>
6338
6339 <varlistentry>
6340 <term><literal>P</literal></term>
6341 <listitem>
6342 <para>
6343 Position: the field value is a decimal ASCII integer, indicating
6344 an error cursor position as an index into the original query string.
6345 The first character has index 1, and positions are measured in
6346 characters not bytes.
6347 </para>
6348 </listitem>
6349 </varlistentry>
6350
6351 <varlistentry>
6352 <term><literal>p</literal></term>
6353 <listitem>
6354 <para>
6355 Internal position: this is defined the same as the <literal>P</literal>
6356 field, but it is used when the cursor position refers to an internally
6357 generated command rather than the one submitted by the client.
6358 The <literal>q</literal> field will always appear when this field appears.
6359 </para>
6360 </listitem>
6361 </varlistentry>
6362
6363 <varlistentry>
6364 <term><literal>q</literal></term>
6365 <listitem>
6366 <para>
6367 Internal query: the text of a failed internally-generated command.
6368 This could be, for example, an SQL query issued by a PL/pgSQL function.
6369 </para>
6370 </listitem>
6371 </varlistentry>
6372
6373 <varlistentry>
6374 <term><literal>W</literal></term>
6375 <listitem>
6376 <para>
6377 Where: an indication of the context in which the error occurred.
6378 Presently this includes a call stack traceback of active
6379 procedural language functions and internally-generated queries.
6380 The trace is one entry per line, most recent first.
6381 </para>
6382 </listitem>
6383 </varlistentry>
6384
6385 <varlistentry>
6386 <term><literal>s</literal></term>
6387 <listitem>
6388 <para>
6389 Schema name: if the error was associated with a specific database
6390 object, the name of the schema containing that object, if any.
6391 </para>
6392 </listitem>
6393 </varlistentry>
6394
6395 <varlistentry>
6396 <term><literal>t</literal></term>
6397 <listitem>
6398 <para>
6399 Table name: if the error was associated with a specific table, the
6400 name of the table. (Refer to the schema name field for the name of
6401 the table's schema.)
6402 </para>
6403 </listitem>
6404 </varlistentry>
6405
6406 <varlistentry>
6407 <term><literal>c</literal></term>
6408 <listitem>
6409 <para>
6410 Column name: if the error was associated with a specific table column,
6411 the name of the column. (Refer to the schema and table name fields to
6412 identify the table.)
6413 </para>
6414 </listitem>
6415 </varlistentry>
6416
6417 <varlistentry>
6418 <term><literal>d</literal></term>
6419 <listitem>
6420 <para>
6421 Data type name: if the error was associated with a specific data type,
6422 the name of the data type. (Refer to the schema name field for the
6423 name of the data type's schema.)
6424 </para>
6425 </listitem>
6426 </varlistentry>
6427
6428 <varlistentry>
6429 <term><literal>n</literal></term>
6430 <listitem>
6431 <para>
6432 Constraint name: if the error was associated with a specific
6433 constraint, the name of the constraint. Refer to fields listed above
6434 for the associated table or domain. (For this purpose, indexes are
6435 treated as constraints, even if they weren't created with constraint
6436 syntax.)
6437 </para>
6438 </listitem>
6439 </varlistentry>
6440
6441 <varlistentry>
6442 <term><literal>F</literal></term>
6443 <listitem>
6444 <para>
6445 File: the file name of the source-code location where the error
6446 was reported.
6447 </para>
6448 </listitem>
6449 </varlistentry>
6450
6451 <varlistentry>
6452 <term><literal>L</literal></term>
6453 <listitem>
6454 <para>
6455 Line: the line number of the source-code location where the error
6456 was reported.
6457 </para>
6458 </listitem>
6459 </varlistentry>
6460
6461 <varlistentry>
6462 <term><literal>R</literal></term>
6463 <listitem>
6464 <para>
6465 Routine: the name of the source-code routine reporting the error.
6466 </para>
6467 </listitem>
6468 </varlistentry>
6469 </variablelist>
6470
6471 <note>
6472 <para>
6473 The fields for schema name, table name, column name, data type name, and
6474 constraint name are supplied only for a limited number of error types;
6475 see <xref linkend="errcodes-appendix"/>. Frontends should not assume that
6476 the presence of any of these fields guarantees the presence of another
6477 field. Core error sources observe the interrelationships noted above, but
6478 user-defined functions may use these fields in other ways. In the same
6479 vein, clients should not assume that these fields denote contemporary
6480 objects in the current database.
6481 </para>
6482 </note>
6483
6484 <para>
6485 The client is responsible for formatting displayed information to meet its
6486 needs; in particular it should break long lines as needed. Newline characters
6487 appearing in the error message fields should be treated as paragraph breaks,
6488 not line breaks.
6489 </para>
6490 </sect1>
6491
6492 <sect1 id="protocol-logicalrep-message-formats">
6493 <title>Logical Replication Message Formats</title>
6494
6495 <para>
6496 This section describes the detailed format of each logical replication
6497 message. These messages are either returned by the replication slot SQL
6498 interface or are sent by a walsender. In the case of a walsender, they are
6499 encapsulated inside replication protocol WAL messages as described in
6500 <xref linkend="protocol-replication"/>, and generally obey the same message
6501 flow as physical replication.
6502 </para>
6503
6504 <variablelist>
6505 <varlistentry id="protocol-logicalrep-message-formats-Begin">
6506 <term>Begin</term>
6507 <listitem>
6508 <variablelist>
6509 <varlistentry>
6510 <term>Byte1('B')</term>
6511 <listitem>
6512 <para>
6513 Identifies the message as a begin message.
6514 </para>
6515 </listitem>
6516 </varlistentry>
6517
6518 <varlistentry>
6519 <term>Int64 (XLogRecPtr)</term>
6520 <listitem>
6521 <para>
6522 The final LSN of the transaction.
6523 </para>
6524 </listitem>
6525 </varlistentry>
6526
6527 <varlistentry>
6528 <term>Int64 (TimestampTz)</term>
6529 <listitem>
6530 <para>
6531 Commit timestamp of the transaction. The value is in number
6532 of microseconds since PostgreSQL epoch (2000-01-01).
6533 </para>
6534 </listitem>
6535 </varlistentry>
6536
6537 <varlistentry>
6538 <term>Int32 (TransactionId)</term>
6539 <listitem>
6540 <para>
6541 Xid of the transaction.
6542 </para>
6543 </listitem>
6544 </varlistentry>
6545 </variablelist>
6546 </listitem>
6547 </varlistentry>
6548
6549 <varlistentry id="protocol-logicalrep-message-formats-Message">
6550 <term>Message</term>
6551 <listitem>
6552 <variablelist>
6553 <varlistentry>
6554 <term>Byte1('M')</term>
6555 <listitem>
6556 <para>
6557 Identifies the message as a logical decoding message.
6558 </para>
6559 </listitem>
6560 </varlistentry>
6561
6562 <varlistentry>
6563 <term>Int32 (TransactionId)</term>
6564 <listitem>
6565 <para>
6566 Xid of the transaction (only present for streamed transactions).
6567 This field is available since protocol version 2.
6568 </para>
6569 </listitem>
6570 </varlistentry>
6571
6572 <varlistentry>
6573 <term>Int8</term>
6574 <listitem>
6575 <para>
6576 Flags; Either 0 for no flags or 1 if the logical decoding
6577 message is transactional.
6578 </para>
6579 </listitem>
6580 </varlistentry>
6581
6582 <varlistentry>
6583 <term>Int64 (XLogRecPtr)</term>
6584 <listitem>
6585 <para>
6586 The LSN of the logical decoding message.
6587 </para>
6588 </listitem>
6589 </varlistentry>
6590
6591 <varlistentry>
6592 <term>String</term>
6593 <listitem>
6594 <para>
6595 The prefix of the logical decoding message.
6596 </para>
6597 </listitem>
6598 </varlistentry>
6599
6600 <varlistentry>
6601 <term>Int32</term>
6602 <listitem>
6603 <para>
6604 Length of the content.
6605 </para>
6606 </listitem>
6607 </varlistentry>
6608
6609 <varlistentry>
6610 <term>Byte<replaceable>n</replaceable></term>
6611 <listitem>
6612 <para>
6613 The content of the logical decoding message.
6614 </para>
6615 </listitem>
6616 </varlistentry>
6617 </variablelist>
6618 </listitem>
6619 </varlistentry>
6620
6621 <varlistentry id="protocol-logicalrep-message-formats-Commit">
6622 <term>Commit</term>
6623 <listitem>
6624 <variablelist>
6625 <varlistentry>
6626 <term>Byte1('C')</term>
6627 <listitem>
6628 <para>
6629 Identifies the message as a commit message.
6630 </para>
6631 </listitem>
6632 </varlistentry>
6633
6634 <varlistentry>
6635 <term>Int8(0)</term>
6636 <listitem>
6637 <para>
6638 Flags; currently unused.
6639 </para>
6640 </listitem>
6641 </varlistentry>
6642
6643 <varlistentry>
6644 <term>Int64 (XLogRecPtr)</term>
6645 <listitem>
6646 <para>
6647 The LSN of the commit.
6648 </para>
6649 </listitem>
6650 </varlistentry>
6651
6652 <varlistentry>
6653 <term>Int64 (XLogRecPtr)</term>
6654 <listitem>
6655 <para>
6656 The end LSN of the transaction.
6657 </para>
6658 </listitem>
6659 </varlistentry>
6660
6661 <varlistentry>
6662 <term>Int64 (TimestampTz)</term>
6663 <listitem>
6664 <para>
6665 Commit timestamp of the transaction. The value is in number
6666 of microseconds since PostgreSQL epoch (2000-01-01).
6667 </para>
6668 </listitem>
6669 </varlistentry>
6670 </variablelist>
6671 </listitem>
6672 </varlistentry>
6673
6674 <varlistentry id="protocol-logicalrep-message-formats-Origin">
6675 <term>Origin</term>
6676 <listitem>
6677 <variablelist>
6678 <varlistentry>
6679 <term>Byte1('O')</term>
6680 <listitem>
6681 <para>
6682 Identifies the message as an origin message.
6683 </para>
6684 </listitem>
6685 </varlistentry>
6686
6687 <varlistentry>
6688 <term>Int64 (XLogRecPtr)</term>
6689 <listitem>
6690 <para>
6691 The LSN of the commit on the origin server.
6692 </para>
6693 </listitem>
6694 </varlistentry>
6695
6696 <varlistentry>
6697 <term>String</term>
6698 <listitem>
6699 <para>
6700 Name of the origin.
6701 </para>
6702 </listitem>
6703 </varlistentry>
6704 </variablelist>
6705
6706 <para>
6707 Note that there can be multiple Origin messages inside a single transaction.
6708 </para>
6709 </listitem>
6710 </varlistentry>
6711
6712 <varlistentry id="protocol-logicalrep-message-formats-Relation">
6713 <term>Relation</term>
6714 <listitem>
6715 <variablelist>
6716 <varlistentry>
6717 <term>Byte1('R')</term>
6718 <listitem>
6719 <para>
6720 Identifies the message as a relation message.
6721 </para>
6722 </listitem>
6723 </varlistentry>
6724
6725 <varlistentry>
6726 <term>Int32 (TransactionId)</term>
6727 <listitem>
6728 <para>
6729 Xid of the transaction (only present for streamed transactions).
6730 This field is available since protocol version 2.
6731 </para>
6732 </listitem>
6733 </varlistentry>
6734
6735 <varlistentry>
6736 <term>Int32 (Oid)</term>
6737 <listitem>
6738 <para>
6739 OID of the relation.
6740 </para>
6741 </listitem>
6742 </varlistentry>
6743
6744 <varlistentry>
6745 <term>String</term>
6746 <listitem>
6747 <para>
6748 Namespace (empty string for <literal>pg_catalog</literal>).
6749 </para>
6750 </listitem>
6751 </varlistentry>
6752
6753 <varlistentry>
6754 <term>String</term>
6755 <listitem>
6756 <para>
6757 Relation name.
6758 </para>
6759 </listitem>
6760 </varlistentry>
6761
6762 <varlistentry>
6763 <term>Int8</term>
6764 <listitem>
6765 <para>
6766 Replica identity setting for the relation (same as
6767 <structfield>relreplident</structfield> in <structname>pg_class</structname>).
6768 </para>
6769 </listitem>
6770 </varlistentry>
6771
6772 <varlistentry>
6773 <term>Int16</term>
6774 <listitem>
6775 <para>
6776 Number of columns.
6777 </para>
6778 </listitem>
6779 </varlistentry>
6780 </variablelist>
6781
6782 <para>
6783 Next, the following message part appears for each column included in
6784 the publication:
6785 </para>
6786
6787 <variablelist>
6788 <varlistentry>
6789 <term>Int8</term>
6790 <listitem>
6791 <para>
6792 Flags for the column. Currently can be either 0 for no flags
6793 or 1 which marks the column as part of the key.
6794 </para>
6795 </listitem>
6796 </varlistentry>
6797
6798 <varlistentry>
6799 <term>String</term>
6800 <listitem>
6801 <para>
6802 Name of the column.
6803 </para>
6804 </listitem>
6805 </varlistentry>
6806
6807 <varlistentry>
6808 <term>Int32 (Oid)</term>
6809 <listitem>
6810 <para>
6811 OID of the column's data type.
6812 </para>
6813 </listitem>
6814 </varlistentry>
6815
6816 <varlistentry>
6817 <term>Int32</term>
6818 <listitem>
6819 <para>
6820 Type modifier of the column (<structfield>atttypmod</structfield>).
6821 </para>
6822 </listitem>
6823 </varlistentry>
6824 </variablelist>
6825 </listitem>
6826 </varlistentry>
6827
6828 <varlistentry id="protocol-logicalrep-message-formats-Type">
6829 <term>Type</term>
6830 <listitem>
6831 <variablelist>
6832 <varlistentry>
6833 <term>Byte1('Y')</term>
6834 <listitem>
6835 <para>
6836 Identifies the message as a type message.
6837 </para>
6838 </listitem>
6839 </varlistentry>
6840
6841 <varlistentry>
6842 <term>Int32 (TransactionId)</term>
6843 <listitem>
6844 <para>
6845 Xid of the transaction (only present for streamed transactions).
6846 This field is available since protocol version 2.
6847 </para>
6848 </listitem>
6849 </varlistentry>
6850
6851 <varlistentry>
6852 <term>Int32 (Oid)</term>
6853 <listitem>
6854 <para>
6855 OID of the data type.
6856 </para>
6857 </listitem>
6858 </varlistentry>
6859
6860 <varlistentry>
6861 <term>String</term>
6862 <listitem>
6863 <para>
6864 Namespace (empty string for <literal>pg_catalog</literal>).
6865 </para>
6866 </listitem>
6867 </varlistentry>
6868
6869 <varlistentry>
6870 <term>String</term>
6871 <listitem>
6872 <para>
6873 Name of the data type.
6874 </para>
6875 </listitem>
6876 </varlistentry>
6877 </variablelist>
6878 </listitem>
6879 </varlistentry>
6880
6881 <varlistentry id="protocol-logicalrep-message-formats-Insert">
6882 <term>Insert</term>
6883 <listitem>
6884 <variablelist>
6885 <varlistentry>
6886 <term>Byte1('I')</term>
6887 <listitem>
6888 <para>
6889 Identifies the message as an insert message.
6890 </para>
6891 </listitem>
6892 </varlistentry>
6893
6894 <varlistentry>
6895 <term>Int32 (TransactionId)</term>
6896 <listitem>
6897 <para>
6898 Xid of the transaction (only present for streamed transactions).
6899 This field is available since protocol version 2.
6900 </para>
6901 </listitem>
6902 </varlistentry>
6903
6904 <varlistentry>
6905 <term>Int32 (Oid)</term>
6906 <listitem>
6907 <para>
6908 OID of the relation corresponding to the ID in the relation
6909 message.
6910 </para>
6911 </listitem>
6912 </varlistentry>
6913
6914 <varlistentry>
6915 <term>Byte1('N')</term>
6916 <listitem>
6917 <para>
6918 Identifies the following TupleData message as a new tuple.
6919 </para>
6920 </listitem>
6921 </varlistentry>
6922
6923 <varlistentry>
6924 <term>TupleData</term>
6925 <listitem>
6926 <para>
6927 TupleData message part representing the contents of new tuple.
6928 </para>
6929 </listitem>
6930 </varlistentry>
6931 </variablelist>
6932 </listitem>
6933 </varlistentry>
6934
6935 <varlistentry id="protocol-logicalrep-message-formats-Update">
6936 <term>Update</term>
6937 <listitem>
6938 <variablelist>
6939 <varlistentry>
6940 <term>Byte1('U')</term>
6941 <listitem>
6942 <para>
6943 Identifies the message as an update message.
6944 </para>
6945 </listitem>
6946 </varlistentry>
6947
6948 <varlistentry>
6949 <term>Int32 (TransactionId)</term>
6950 <listitem>
6951 <para>
6952 Xid of the transaction (only present for streamed transactions).
6953 This field is available since protocol version 2.
6954 </para>
6955 </listitem>
6956 </varlistentry>
6957
6958 <varlistentry>
6959 <term>Int32 (Oid)</term>
6960 <listitem>
6961 <para>
6962 OID of the relation corresponding to the ID in the relation
6963 message.
6964 </para>
6965 </listitem>
6966 </varlistentry>
6967
6968 <varlistentry>
6969 <term>Byte1('K')</term>
6970 <listitem>
6971 <para>
6972 Identifies the following TupleData submessage as a key.
6973 This field is optional and is only present if
6974 the update changed data in any of the column(s) that are
6975 part of the REPLICA IDENTITY index.
6976 </para>
6977 </listitem>
6978 </varlistentry>
6979
6980 <varlistentry>
6981 <term>Byte1('O')</term>
6982 <listitem>
6983 <para>
6984 Identifies the following TupleData submessage as an old tuple.
6985 This field is optional and is only present if table in which
6986 the update happened has REPLICA IDENTITY set to FULL.
6987 </para>
6988 </listitem>
6989 </varlistentry>
6990
6991 <varlistentry>
6992 <term>TupleData</term>
6993 <listitem>
6994 <para>
6995 TupleData message part representing the contents of the old tuple
6996 or primary key. Only present if the previous 'O' or 'K' part
6997 is present.
6998 </para>
6999 </listitem>
7000 </varlistentry>
7001
7002 <varlistentry>
7003 <term>Byte1('N')</term>
7004 <listitem>
7005 <para>
7006 Identifies the following TupleData message as a new tuple.
7007 </para>
7008 </listitem>
7009 </varlistentry>
7010
7011 <varlistentry>
7012 <term>TupleData</term>
7013 <listitem>
7014 <para>
7015 TupleData message part representing the contents of a new tuple.
7016 </para>
7017 </listitem>
7018 </varlistentry>
7019 </variablelist>
7020
7021 <para>
7022 The Update message may contain either a 'K' message part or an 'O' message part
7023 or neither of them, but never both of them.
7024 </para>
7025 </listitem>
7026 </varlistentry>
7027
7028 <varlistentry id="protocol-logicalrep-message-formats-Delete">
7029 <term>Delete</term>
7030 <listitem>
7031 <variablelist>
7032 <varlistentry>
7033 <term>Byte1('D')</term>
7034 <listitem>
7035 <para>
7036 Identifies the message as a delete message.
7037 </para>
7038 </listitem>
7039 </varlistentry>
7040
7041 <varlistentry>
7042 <term>Int32 (TransactionId)</term>
7043 <listitem>
7044 <para>
7045 Xid of the transaction (only present for streamed transactions).
7046 This field is available since protocol version 2.
7047 </para>
7048 </listitem>
7049 </varlistentry>
7050
7051 <varlistentry>
7052 <term>Int32 (Oid)</term>
7053 <listitem>
7054 <para>
7055 OID of the relation corresponding to the ID in the relation
7056 message.
7057 </para>
7058 </listitem>
7059 </varlistentry>
7060
7061 <varlistentry>
7062 <term>Byte1('K')</term>
7063 <listitem>
7064 <para>
7065 Identifies the following TupleData submessage as a key.
7066 This field is present if the table in which the delete has
7067 happened uses an index as REPLICA IDENTITY.
7068 </para>
7069 </listitem>
7070 </varlistentry>
7071
7072 <varlistentry>
7073 <term>Byte1('O')</term>
7074 <listitem>
7075 <para>
7076 Identifies the following TupleData message as an old tuple.
7077 This field is present if the table in which the delete
7078 happened has REPLICA IDENTITY set to FULL.
7079 </para>
7080 </listitem>
7081 </varlistentry>
7082
7083 <varlistentry>
7084 <term>TupleData</term>
7085 <listitem>
7086 <para>
7087 TupleData message part representing the contents of the old tuple
7088 or primary key, depending on the previous field.
7089 </para>
7090 </listitem>
7091 </varlistentry>
7092 </variablelist>
7093
7094 <para>
7095 The Delete message may contain either a 'K' message part or an 'O' message part,
7096 but never both of them.
7097 </para>
7098 </listitem>
7099 </varlistentry>
7100
7101 <varlistentry id="protocol-logicalrep-message-formats-Truncate">
7102 <term>Truncate</term>
7103 <listitem>
7104 <variablelist>
7105 <varlistentry>
7106 <term>Byte1('T')</term>
7107 <listitem>
7108 <para>
7109 Identifies the message as a truncate message.
7110 </para>
7111 </listitem>
7112 </varlistentry>
7113
7114 <varlistentry>
7115 <term>Int32 (TransactionId)</term>
7116 <listitem>
7117 <para>
7118 Xid of the transaction (only present for streamed transactions).
7119 This field is available since protocol version 2.
7120 </para>
7121 </listitem>
7122 </varlistentry>
7123
7124 <varlistentry>
7125 <term>Int32</term>
7126 <listitem>
7127 <para>
7128 Number of relations
7129 </para>
7130 </listitem>
7131 </varlistentry>
7132
7133 <varlistentry>
7134 <term>Int8</term>
7135 <listitem>
7136 <para>
7137 Option bits for <command>TRUNCATE</command>:
7138 1 for <literal>CASCADE</literal>, 2 for <literal>RESTART IDENTITY</literal>
7139 </para>
7140 </listitem>
7141 </varlistentry>
7142
7143 <varlistentry>
7144 <term>Int32 (Oid)</term>
7145 <listitem>
7146 <para>
7147 OID of the relation corresponding to the ID in the relation
7148 message. This field is repeated for each relation.
7149 </para>
7150 </listitem>
7151 </varlistentry>
7152 </variablelist>
7153 </listitem>
7154 </varlistentry>
7155 </variablelist>
7156
7157 <para>
7158 The following messages (Stream Start, Stream Stop, Stream Commit, and
7159 Stream Abort) are available since protocol version 2.
7160 </para>
7161
7162 <variablelist>
7163 <varlistentry id="protocol-logicalrep-message-formats-Stream-Start">
7164 <term>Stream Start</term>
7165 <listitem>
7166 <variablelist>
7167 <varlistentry>
7168 <term>Byte1('S')</term>
7169 <listitem>
7170 <para>
7171 Identifies the message as a stream start message.
7172 </para>
7173 </listitem>
7174 </varlistentry>
7175
7176 <varlistentry>
7177 <term>Int32 (TransactionId)</term>
7178 <listitem>
7179 <para>
7180 Xid of the transaction.
7181 </para>
7182 </listitem>
7183 </varlistentry>
7184
7185 <varlistentry>
7186 <term>Int8</term>
7187 <listitem>
7188 <para>
7189 A value of 1 indicates this is the first stream segment for
7190 this XID, 0 for any other stream segment.
7191 </para>
7192 </listitem>
7193 </varlistentry>
7194 </variablelist>
7195 </listitem>
7196 </varlistentry>
7197
7198 <varlistentry id="protocol-logicalrep-message-formats-Stream-Stop">
7199 <term>Stream Stop</term>
7200 <listitem>
7201 <variablelist>
7202 <varlistentry>
7203 <term>Byte1('E')</term>
7204 <listitem>
7205 <para>
7206 Identifies the message as a stream stop message.
7207 </para>
7208 </listitem>
7209 </varlistentry>
7210 </variablelist>
7211 </listitem>
7212 </varlistentry>
7213
7214 <varlistentry id="protocol-logicalrep-message-formats-Stream-Commit">
7215 <term>Stream Commit</term>
7216 <listitem>
7217 <variablelist>
7218 <varlistentry>
7219 <term>Byte1('c')</term>
7220 <listitem>
7221 <para>
7222 Identifies the message as a stream commit message.
7223 </para>
7224 </listitem>
7225 </varlistentry>
7226
7227 <varlistentry>
7228 <term>Int32 (TransactionId)</term>
7229 <listitem>
7230 <para>
7231 Xid of the transaction.
7232 </para>
7233 </listitem>
7234 </varlistentry>
7235
7236 <varlistentry>
7237 <term>Int8(0)</term>
7238 <listitem>
7239 <para>
7240 Flags; currently unused.
7241 </para>
7242 </listitem>
7243 </varlistentry>
7244
7245 <varlistentry>
7246 <term>Int64 (XLogRecPtr)</term>
7247 <listitem>
7248 <para>
7249 The LSN of the commit.
7250 </para>
7251 </listitem>
7252 </varlistentry>
7253
7254 <varlistentry>
7255 <term>Int64 (XLogRecPtr)</term>
7256 <listitem>
7257 <para>
7258 The end LSN of the transaction.
7259 </para>
7260 </listitem>
7261 </varlistentry>
7262
7263 <varlistentry>
7264 <term>Int64 (TimestampTz)</term>
7265 <listitem>
7266 <para>
7267 Commit timestamp of the transaction. The value is in number
7268 of microseconds since PostgreSQL epoch (2000-01-01).
7269 </para>
7270 </listitem>
7271 </varlistentry>
7272 </variablelist>
7273 </listitem>
7274 </varlistentry>
7275
7276 <varlistentry id="protocol-logicalrep-message-formats-Stream-Abort">
7277 <term>Stream Abort</term>
7278 <listitem>
7279 <variablelist>
7280 <varlistentry>
7281 <term>Byte1('A')</term>
7282 <listitem>
7283 <para>
7284 Identifies the message as a stream abort message.
7285 </para>
7286 </listitem>
7287 </varlistentry>
7288
7289 <varlistentry>
7290 <term>Int32 (TransactionId)</term>
7291 <listitem>
7292 <para>
7293 Xid of the transaction.
7294 </para>
7295 </listitem>
7296 </varlistentry>
7297
7298 <varlistentry>
7299 <term>Int32 (TransactionId)</term>
7300 <listitem>
7301 <para>
7302 Xid of the subtransaction (will be same as xid of the transaction for top-level
7303 transactions).
7304 </para>
7305 </listitem>
7306 </varlistentry>
7307
7308 <varlistentry>
7309 <term>Int64 (XLogRecPtr)</term>
7310 <listitem>
7311 <para>
7312 The LSN of the abort operation, present only when streaming is set to parallel.
7313 This field is available since protocol version 4.
7314 </para>
7315 </listitem>
7316 </varlistentry>
7317
7318 <varlistentry>
7319 <term>Int64 (TimestampTz)</term>
7320 <listitem>
7321 <para>
7322 Abort timestamp of the transaction, present only when streaming is set to
7323 parallel. The value is in number of microseconds since PostgreSQL epoch (2000-01-01).
7324 This field is available since protocol version 4.
7325 </para>
7326 </listitem>
7327 </varlistentry>
7328
7329 </variablelist>
7330 </listitem>
7331 </varlistentry>
7332 </variablelist>
7333
7334 <para>
7335 The following messages (Begin Prepare, Prepare, Commit Prepared, Rollback Prepared, Stream Prepare)
7336 are available since protocol version 3.
7337 </para>
7338
7339 <variablelist>
7340 <varlistentry id="protocol-logicalrep-message-formats-Begin-Prepare">
7341 <term>Begin Prepare</term>
7342 <listitem>
7343 <variablelist>
7344 <varlistentry>
7345 <term>Byte1('b')</term>
7346 <listitem>
7347 <para>
7348 Identifies the message as the beginning of a prepared transaction message.
7349 </para>
7350 </listitem>
7351 </varlistentry>
7352
7353 <varlistentry>
7354 <term>Int64 (XLogRecPtr)</term>
7355 <listitem>
7356 <para>
7357 The LSN of the prepare.
7358 </para>
7359 </listitem>
7360 </varlistentry>
7361
7362 <varlistentry>
7363 <term>Int64 (XLogRecPtr)</term>
7364 <listitem>
7365 <para>
7366 The end LSN of the prepared transaction.
7367 </para>
7368 </listitem>
7369 </varlistentry>
7370
7371 <varlistentry>
7372 <term>Int64 (TimestampTz)</term>
7373 <listitem>
7374 <para>
7375 Prepare timestamp of the transaction. The value is in number
7376 of microseconds since PostgreSQL epoch (2000-01-01).
7377 </para>
7378 </listitem>
7379 </varlistentry>
7380
7381 <varlistentry>
7382 <term>Int32 (TransactionId)</term>
7383 <listitem>
7384 <para>
7385 Xid of the transaction.
7386 </para>
7387 </listitem>
7388 </varlistentry>
7389
7390 <varlistentry>
7391 <term>String</term>
7392 <listitem>
7393 <para>
7394 The user defined GID of the prepared transaction.
7395 </para>
7396 </listitem>
7397 </varlistentry>
7398 </variablelist>
7399 </listitem>
7400 </varlistentry>
7401
7402 <varlistentry id="protocol-logicalrep-message-formats-Prepare">
7403 <term>Prepare</term>
7404 <listitem>
7405 <variablelist>
7406 <varlistentry>
7407 <term>Byte1('P')</term>
7408 <listitem>
7409 <para>
7410 Identifies the message as a prepared transaction message.
7411 </para>
7412 </listitem>
7413 </varlistentry>
7414
7415 <varlistentry>
7416 <term>Int8(0)</term>
7417 <listitem>
7418 <para>
7419 Flags; currently unused.
7420 </para>
7421 </listitem>
7422 </varlistentry>
7423
7424 <varlistentry>
7425 <term>Int64 (XLogRecPtr)</term>
7426 <listitem>
7427 <para>
7428 The LSN of the prepare.
7429 </para>
7430 </listitem>
7431 </varlistentry>
7432
7433 <varlistentry>
7434 <term>Int64 (XLogRecPtr)</term>
7435 <listitem>
7436 <para>
7437 The end LSN of the prepared transaction.
7438 </para>
7439 </listitem>
7440 </varlistentry>
7441
7442 <varlistentry>
7443 <term>Int64 (TimestampTz)</term>
7444 <listitem>
7445 <para>
7446 Prepare timestamp of the transaction. The value is in number
7447 of microseconds since PostgreSQL epoch (2000-01-01).
7448 </para>
7449 </listitem>
7450 </varlistentry>
7451
7452 <varlistentry>
7453 <term>Int32 (TransactionId)</term>
7454 <listitem>
7455 <para>
7456 Xid of the transaction.
7457 </para>
7458 </listitem>
7459 </varlistentry>
7460
7461 <varlistentry>
7462 <term>String</term>
7463 <listitem>
7464 <para>
7465 The user defined GID of the prepared transaction.
7466 </para>
7467 </listitem>
7468 </varlistentry>
7469 </variablelist>
7470 </listitem>
7471 </varlistentry>
7472
7473 <varlistentry id="protocol-logicalrep-message-formats-Commit-Prepared">
7474 <term>Commit Prepared</term>
7475 <listitem>
7476 <variablelist>
7477 <varlistentry>
7478 <term>Byte1('K')</term>
7479 <listitem>
7480 <para>
7481 Identifies the message as the commit of a prepared transaction message.
7482 </para>
7483 </listitem>
7484 </varlistentry>
7485
7486 <varlistentry>
7487 <term>Int8(0)</term>
7488 <listitem>
7489 <para>
7490 Flags; currently unused.
7491 </para>
7492 </listitem>
7493 </varlistentry>
7494
7495 <varlistentry>
7496 <term>Int64 (XLogRecPtr)</term>
7497 <listitem>
7498 <para>
7499 The LSN of the commit of the prepared transaction.
7500 </para>
7501 </listitem>
7502 </varlistentry>
7503
7504 <varlistentry>
7505 <term>Int64 (XLogRecPtr)</term>
7506 <listitem>
7507 <para>
7508 The end LSN of the commit of the prepared transaction.
7509 </para>
7510 </listitem>
7511 </varlistentry>
7512
7513 <varlistentry>
7514 <term>Int64 (TimestampTz)</term>
7515 <listitem>
7516 <para>
7517 Commit timestamp of the transaction. The value is in number
7518 of microseconds since PostgreSQL epoch (2000-01-01).
7519 </para>
7520 </listitem>
7521 </varlistentry>
7522
7523 <varlistentry>
7524 <term>Int32 (TransactionId)</term>
7525 <listitem>
7526 <para>
7527 Xid of the transaction.
7528 </para>
7529 </listitem>
7530 </varlistentry>
7531
7532 <varlistentry>
7533 <term>String</term>
7534 <listitem>
7535 <para>
7536 The user defined GID of the prepared transaction.
7537 </para>
7538 </listitem>
7539 </varlistentry>
7540 </variablelist>
7541 </listitem>
7542 </varlistentry>
7543
7544 <varlistentry id="protocol-logicalrep-message-formats-Rollback-Prepared">
7545 <term>Rollback Prepared</term>
7546 <listitem>
7547 <variablelist>
7548 <varlistentry>
7549 <term>Byte1('r')</term>
7550 <listitem>
7551 <para>
7552 Identifies the message as the rollback of a prepared transaction message.
7553 </para>
7554 </listitem>
7555 </varlistentry>
7556
7557 <varlistentry>
7558 <term>Int8(0)</term>
7559 <listitem>
7560 <para>
7561 Flags; currently unused.
7562 </para>
7563 </listitem>
7564 </varlistentry>
7565
7566 <varlistentry>
7567 <term>Int64 (XLogRecPtr)</term>
7568 <listitem>
7569 <para>
7570 The end LSN of the prepared transaction.
7571 </para>
7572 </listitem>
7573 </varlistentry>
7574
7575 <varlistentry>
7576 <term>Int64 (XLogRecPtr)</term>
7577 <listitem>
7578 <para>
7579 The end LSN of the rollback of the prepared transaction.
7580 </para>
7581 </listitem>
7582 </varlistentry>
7583
7584 <varlistentry>
7585 <term>Int64 (TimestampTz)</term>
7586 <listitem>
7587 <para>
7588 Prepare timestamp of the transaction. The value is in number
7589 of microseconds since PostgreSQL epoch (2000-01-01).
7590 </para>
7591 </listitem>
7592 </varlistentry>
7593
7594 <varlistentry>
7595 <term>Int64 (TimestampTz)</term>
7596 <listitem>
7597 <para>
7598 Rollback timestamp of the transaction. The value is in number
7599 of microseconds since PostgreSQL epoch (2000-01-01).
7600 </para>
7601 </listitem>
7602 </varlistentry>
7603
7604 <varlistentry>
7605 <term>Int32 (TransactionId)</term>
7606 <listitem>
7607 <para>
7608 Xid of the transaction.
7609 </para>
7610 </listitem>
7611 </varlistentry>
7612
7613 <varlistentry>
7614 <term>String</term>
7615 <listitem>
7616 <para>
7617 The user defined GID of the prepared transaction.
7618 </para>
7619 </listitem>
7620 </varlistentry>
7621 </variablelist>
7622 </listitem>
7623 </varlistentry>
7624
7625 <varlistentry id="protocol-logicalrep-message-formats-Stream-Prepare">
7626 <term>Stream Prepare</term>
7627 <listitem>
7628 <variablelist>
7629 <varlistentry>
7630 <term>Byte1('p')</term>
7631 <listitem>
7632 <para>
7633 Identifies the message as a stream prepared transaction message.
7634 </para>
7635 </listitem>
7636 </varlistentry>
7637
7638 <varlistentry>
7639 <term>Int8(0)</term>
7640 <listitem>
7641 <para>
7642 Flags; currently unused.
7643 </para>
7644 </listitem>
7645 </varlistentry>
7646
7647 <varlistentry>
7648 <term>Int64 (XLogRecPtr)</term>
7649 <listitem>
7650 <para>
7651 The LSN of the prepare.
7652 </para>
7653 </listitem>
7654 </varlistentry>
7655
7656 <varlistentry>
7657 <term>Int64 (XLogRecPtr)</term>
7658 <listitem>
7659 <para>
7660 The end LSN of the prepared transaction.
7661 </para>
7662 </listitem>
7663 </varlistentry>
7664
7665 <varlistentry>
7666 <term>Int64 (TimestampTz)</term>
7667 <listitem>
7668 <para>
7669 Prepare timestamp of the transaction. The value is in number
7670 of microseconds since PostgreSQL epoch (2000-01-01).
7671 </para>
7672 </listitem>
7673 </varlistentry>
7674
7675 <varlistentry>
7676 <term>Int32 (TransactionId)</term>
7677 <listitem>
7678 <para>
7679 Xid of the transaction.
7680 </para>
7681 </listitem>
7682 </varlistentry>
7683
7684 <varlistentry>
7685 <term>String</term>
7686 <listitem>
7687 <para>
7688 The user defined GID of the prepared transaction.
7689 </para>
7690 </listitem>
7691 </varlistentry>
7692 </variablelist>
7693 </listitem>
7694 </varlistentry>
7695 </variablelist>
7696
7697 <para>
7698 The following message parts are shared by the above messages.
7699 </para>
7700
7701 <variablelist>
7702 <varlistentry id="protocol-logicalrep-message-formats-TupleData">
7703 <term>TupleData</term>
7704 <listitem>
7705 <variablelist>
7706 <varlistentry>
7707 <term>Int16</term>
7708 <listitem>
7709 <para>
7710 Number of columns.
7711 </para>
7712 </listitem>
7713 </varlistentry>
7714 </variablelist>
7715
7716 <para>
7717 Next, one of the following submessages appears for each published column:
7718
7719 <variablelist>
7720 <varlistentry>
7721 <term>Byte1('n')</term>
7722 <listitem>
7723 <para>
7724 Identifies the data as NULL value.
7725 </para>
7726 </listitem>
7727 </varlistentry>
7728 </variablelist>
7729 Or
7730 <variablelist>
7731 <varlistentry>
7732 <term>Byte1('u')</term>
7733 <listitem>
7734 <para>
7735 Identifies unchanged TOASTed value (the actual value is not
7736 sent).
7737 </para>
7738 </listitem>
7739 </varlistentry>
7740 </variablelist>
7741 Or
7742 <variablelist>
7743 <varlistentry>
7744 <term>Byte1('t')</term>
7745 <listitem>
7746 <para>
7747 Identifies the data as text formatted value.
7748 </para>
7749 </listitem>
7750 </varlistentry>
7751 </variablelist>
7752 Or
7753 <variablelist>
7754 <varlistentry>
7755 <term>Byte1('b')</term>
7756 <listitem>
7757 <para>
7758 Identifies the data as binary formatted value.
7759 </para>
7760 </listitem>
7761 </varlistentry>
7762
7763 <varlistentry>
7764 <term>Int32</term>
7765 <listitem>
7766 <para>
7767 Length of the column value.
7768 </para>
7769 </listitem>
7770 </varlistentry>
7771
7772 <varlistentry>
7773 <term>Byte<replaceable>n</replaceable></term>
7774 <listitem>
7775 <para>
7776 The value of the column, either in binary or in text format.
7777 (As specified in the preceding format byte).
7778 <replaceable>n</replaceable> is the above length.
7779 </para>
7780 </listitem>
7781 </varlistentry>
7782 </variablelist>
7783 </para>
7784 </listitem>
7785 </varlistentry>
7786 </variablelist>
7787 </sect1>
7788
7789 <sect1 id="protocol-changes">
7790 <title>Summary of Changes since Protocol 2.0</title>
7791
7792 <para>
7793 This section provides a quick checklist of changes, for the benefit of
7794 developers trying to update existing client libraries to protocol 3.0.
7795 </para>
7796
7797 <para>
7798 The initial startup packet uses a flexible list-of-strings format
7799 instead of a fixed format. Notice that session default values for run-time
7800 parameters can now be specified directly in the startup packet. (Actually,
7801 you could do that before using the <literal>options</literal> field, but given the
7802 limited width of <literal>options</literal> and the lack of any way to quote
7803 whitespace in the values, it wasn't a very safe technique.)
7804 </para>
7805
7806 <para>
7807 All messages now have a length count immediately following the message type
7808 byte (except for startup packets, which have no type byte). Also note that
7809 PasswordMessage now has a type byte.
7810 </para>
7811
7812 <para>
7813 ErrorResponse and NoticeResponse ('<literal>E</literal>' and '<literal>N</literal>')
7814 messages now contain multiple fields, from which the client code can
7815 assemble an error message of the desired level of verbosity. Note that
7816 individual fields will typically not end with a newline, whereas the single
7817 string sent in the older protocol always did.
7818 </para>
7819
7820 <para>
7821 The ReadyForQuery ('<literal>Z</literal>') message includes a transaction status
7822 indicator.
7823 </para>
7824
7825 <para>
7826 The distinction between BinaryRow and DataRow message types is gone; the
7827 single DataRow message type serves for returning data in all formats.
7828 Note that the layout of DataRow has changed to make it easier to parse.
7829 Also, the representation of binary values has changed: it is no longer
7830 directly tied to the server's internal representation.
7831 </para>
7832
7833 <para>
7834 There is a new <quote>extended query</quote> sub-protocol, which adds the frontend
7835 message types Parse, Bind, Execute, Describe, Close, Flush, and Sync, and the
7836 backend message types ParseComplete, BindComplete, PortalSuspended,
7837 ParameterDescription, NoData, and CloseComplete. Existing clients do not
7838 have to concern themselves with this sub-protocol, but making use of it
7839 might allow improvements in performance or functionality.
7840 </para>
7841
7842 <para>
7843 <command>COPY</command> data is now encapsulated into CopyData and CopyDone messages. There
7844 is a well-defined way to recover from errors during <command>COPY</command>. The special
7845 <quote><literal>\.</literal></quote> last line is not needed anymore, and is not sent
7846 during <command>COPY OUT</command>.
7847 (It is still recognized as a terminator during text-mode <command>COPY
7848 IN</command>, but not in CSV mode. The text-mode behavior is
7849 deprecated and may eventually be removed.) Binary <command>COPY</command> is supported.
7850 The CopyInResponse and CopyOutResponse messages include fields indicating
7851 the number of columns and the format of each column.
7852 </para>
7853
7854 <para>
7855 The layout of FunctionCall and FunctionCallResponse messages has changed.
7856 FunctionCall can now support passing NULL arguments to functions. It also
7857 can handle passing parameters and retrieving results in either text or
7858 binary format. There is no longer any reason to consider FunctionCall a
7859 potential security hole, since it does not offer direct access to internal
7860 server data representations.
7861 </para>
7862
7863 <para>
7864 The backend sends ParameterStatus ('<literal>S</literal>') messages during connection
7865 startup for all parameters it considers interesting to the client library.
7866 Subsequently, a ParameterStatus message is sent whenever the active value
7867 changes for any of these parameters.
7868 </para>
7869
7870 <para>
7871 The RowDescription ('<literal>T</literal>') message carries new table OID and column
7872 number fields for each column of the described row. It also shows the format
7873 code for each column.
7874 </para>
7875
7876 <para>
7877 The CursorResponse ('<literal>P</literal>') message is no longer generated by
7878 the backend.
7879 </para>
7880
7881 <para>
7882 The NotificationResponse ('<literal>A</literal>') message has an additional string
7883 field, which can carry a <quote>payload</quote> string passed
7884 from the <command>NOTIFY</command> event sender.
7885 </para>
7886
7887 <para>
7888 The EmptyQueryResponse ('<literal>I</literal>') message used to include an empty
7889 string parameter; this has been removed.
7890 </para>
7891 </sect1>
7892 </chapter>