diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml index cc5c8dc574ce..51b311ce1d11 100644 --- a/doc/src/sgml/protocol.sgml +++ b/doc/src/sgml/protocol.sgml @@ -7880,106 +7880,160 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Summary of Changes since Protocol 2.0 + Summary of Protocol Changes This section provides a quick checklist of changes, for the benefit of - developers trying to update existing client libraries to protocol 3.0. + developers trying to update existing client libraries to the most recent + protocol version. - - The initial startup packet uses a flexible list-of-strings format - instead of a fixed format. Notice that session default values for run-time - parameters can now be specified directly in the startup packet. (Actually, - you could do that before using the options field, but given the - limited width of options and the lack of any way to quote - whitespace in the values, it wasn't a very safe technique.) - + + Protocol changes introduced in version 3.2 - - All messages now have a length count immediately following the message type - byte (except for startup packets, which have no type byte). Also note that - PasswordMessage now has a type byte. - + + Protocol version 3.2 was introduced in PostgreSQL 18. + - - ErrorResponse and NoticeResponse ('E' and 'N') - messages now contain multiple fields, from which the client code can - assemble an error message of the desired level of verbosity. Note that - individual fields will typically not end with a newline, whereas the single - string sent in the older protocol always did. - + + The BackendKeyData and CancelRequest messages were changed to allow a + variable size for the secret key instead of the 32-bit fixed size the + secret had before. The maximum size of the secret is now 256 bytes. + + - - The ReadyForQuery ('Z') message includes a transaction status - indicator. - + + Protocol changes introduced in version 3.0 without a protocol version bump - - The distinction between BinaryRow and DataRow message types is gone; the - single DataRow message type serves for returning data in all formats. - Note that the layout of DataRow has changed to make it easier to parse. - Also, the representation of binary values has changed: it is no longer - directly tied to the server's internal representation. - + + During the lifetime of protocol version 3.0 some changes to this protocol + version were made without bumping the protocol version. These changes are + listed below. + - - There is a new extended query sub-protocol, which adds the frontend - message types Parse, Bind, Execute, Describe, Close, Flush, and Sync, and the - backend message types ParseComplete, BindComplete, PortalSuspended, - ParameterDescription, NoData, and CloseComplete. Existing clients do not - have to concern themselves with this sub-protocol, but making use of it - might allow improvements in performance or functionality. - + + In PostgreSQL 9.3.21 the + NegotiateProtocolVersion message was introduced. This allows servers to + indicate to the client that it does not support the protocol version that + was requested by the client and that it wants to downgrade to a lower one. + - - COPY data is now encapsulated into CopyData and CopyDone messages. There - is a well-defined way to recover from errors during COPY. The special - \. last line is not needed anymore, and is not sent - during COPY OUT. - (It is still recognized as a terminator during text-mode COPY - IN, but not in CSV mode. The text-mode behavior is - deprecated and may eventually be removed.) Binary COPY is supported. - The CopyInResponse and CopyOutResponse messages include fields indicating - the number of columns and the format of each column. - + + In PostgreSQL 17 SSL negotiation was modified. + Before version 17 To initiate an SSL-encrypted connection, the frontend initially + sends an SSLRequest message rather than a StartupMessage. The server then responds + with a single byte containing S or N, indicating that it is willing or unwilling + to perform SSL, respectively. After which the frontend begins SSL negotiation + Starting in version 17 the server will also recognize connections which + immediately begin SSL negotiation without any previous SSLRequest packets + + - - The layout of FunctionCall and FunctionCallResponse messages has changed. - FunctionCall can now support passing NULL arguments to functions. It also - can handle passing parameters and retrieving results in either text or - binary format. There is no longer any reason to consider FunctionCall a - potential security hole, since it does not offer direct access to internal - server data representations. - + + Protocol changes introduced in version 3.0 - - The backend sends ParameterStatus ('S') messages during connection - startup for all parameters it considers interesting to the client library. - Subsequently, a ParameterStatus message is sent whenever the active value - changes for any of these parameters. - + + Protocol version 3.0 was introduced in + PostgreSQL 7.4. It introduced many changes + compared to the previous 2.0 protocol version. These changes are listed + below, although mostly for historical reasons, since protocol version 2.0 + has not been supported by servers and clients for quite a long time. + - - The RowDescription ('T') message carries new table OID and column - number fields for each column of the described row. It also shows the format - code for each column. - + + The initial startup packet uses a flexible list-of-strings format + instead of a fixed format. Notice that session default values for run-time + parameters can now be specified directly in the startup packet. (Actually, + you could do that before using the options field, but given the + limited width of options and the lack of any way to quote + whitespace in the values, it wasn't a very safe technique.) + - - The CursorResponse ('P') message is no longer generated by - the backend. - + + All messages now have a length count immediately following the message type + byte (except for startup packets, which have no type byte). Also note that + PasswordMessage now has a type byte. + - - The NotificationResponse ('A') message has an additional string - field, which can carry a payload string passed - from the NOTIFY event sender. - + + ErrorResponse and NoticeResponse ('E' and 'N') + messages now contain multiple fields, from which the client code can + assemble an error message of the desired level of verbosity. Note that + individual fields will typically not end with a newline, whereas the single + string sent in the older protocol always did. + - - The EmptyQueryResponse ('I') message used to include an empty - string parameter; this has been removed. - + + The ReadyForQuery ('Z') message includes a transaction status + indicator. + + + + The distinction between BinaryRow and DataRow message types is gone; the + single DataRow message type serves for returning data in all formats. + Note that the layout of DataRow has changed to make it easier to parse. + Also, the representation of binary values has changed: it is no longer + directly tied to the server's internal representation. + + + + There is a new extended query sub-protocol, which adds the frontend + message types Parse, Bind, Execute, Describe, Close, Flush, and Sync, and the + backend message types ParseComplete, BindComplete, PortalSuspended, + ParameterDescription, NoData, and CloseComplete. Existing clients do not + have to concern themselves with this sub-protocol, but making use of it + might allow improvements in performance or functionality. + + + + COPY data is now encapsulated into CopyData and CopyDone messages. There + is a well-defined way to recover from errors during COPY. The special + \. last line is not needed anymore, and is not sent + during COPY OUT. + (It is still recognized as a terminator during text-mode COPY + IN, but not in CSV mode. The text-mode behavior is + deprecated and may eventually be removed.) Binary COPY is supported. + The CopyInResponse and CopyOutResponse messages include fields indicating + the number of columns and the format of each column. + + + + The layout of FunctionCall and FunctionCallResponse messages has changed. + FunctionCall can now support passing NULL arguments to functions. It also + can handle passing parameters and retrieving results in either text or + binary format. There is no longer any reason to consider FunctionCall a + potential security hole, since it does not offer direct access to internal + server data representations. + + + + The backend sends ParameterStatus ('S') messages during connection + startup for all parameters it considers interesting to the client library. + Subsequently, a ParameterStatus message is sent whenever the active value + changes for any of these parameters. + + + + The RowDescription ('T') message carries new table OID and column + number fields for each column of the described row. It also shows the format + code for each column. + + + + The CursorResponse ('P') message is no longer generated by + the backend. + + + + The NotificationResponse ('A') message has an additional string + field, which can carry a payload string passed + from the NOTIFY event sender. + + + + The EmptyQueryResponse ('I') message used to include an empty + string parameter; this has been removed. + +