From a5cb4f9829fbfd68655543d2d371a18a8eb43b84 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Mon, 2 Aug 2021 11:32:17 -0400 Subject: [PATCH] Doc: minor improvements for logical replication protocol documentation. Where appropriate, annotate message field data types with the backend code's name for the data type, eg XLogRecPtr or TimestampTz. Previously we just said "Int64" which didn't provide as much info. Also clarify references to object OIDs, and make use of the existing convention to denote the value of a field that must have a fixed value. Vignesh C, reviewed by Peter Smith and Euler Taveira. Discussion: https://postgr.es/m/CALDaNm0+fatx57KFcBopUZWQpH_tz3WKKfm-_eiTwcXui5BnhQ@mail.gmail.com --- doc/src/sgml/protocol.sgml | 179 +++++++++++++++++++++++-------------- 1 file changed, 110 insertions(+), 69 deletions(-) diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml index 9843953b05..991994de1d 100644 --- a/doc/src/sgml/protocol.sgml +++ b/doc/src/sgml/protocol.sgml @@ -2892,7 +2892,7 @@ The commands accepted in replication mode are: belong to the same transaction. Similarly, all messages between a pair of Begin Prepare and Prepare messages belong to the same transaction. It also sends changes of large in-progress transactions between a pair of - Stream Start and Stream Stop messages. The last stream of such a transaction + Stream Start and Stream Stop messages. The last stream of such a transaction contains a Stream Commit or Stream Abort message. @@ -6407,11 +6407,12 @@ not line breaks. Logical Replication Message Formats -This section describes the detailed format of each logical replication message. -These messages are returned either by the replication slot SQL interface or are -sent by a walsender. In case of a walsender they are encapsulated inside the replication -protocol WAL messages as described in -and generally obey same message flow as physical replication. +This section describes the detailed format of each logical replication +message. These messages are either returned by the replication slot SQL +interface or are sent by a walsender. In the case of a walsender they are +encapsulated inside replication protocol WAL messages as described in +, and generally obey the same message +flow as physical replication. @@ -6436,7 +6437,7 @@ Begin - Int64 + Int64 (XLogRecPtr) @@ -6446,7 +6447,7 @@ Begin - Int64 + Int64 (TimestampTz) @@ -6457,7 +6458,7 @@ Begin - Int32 + Int32 (TransactionId) @@ -6491,7 +6492,7 @@ Message - Int32 + Int32 (TransactionId) @@ -6513,7 +6514,7 @@ Message - Int64 + Int64 (XLogRecPtr) @@ -6579,17 +6580,17 @@ Commit - Int8 + Int8(0) - Flags; currently unused (must be 0). + Flags; currently unused. - Int64 + Int64 (XLogRecPtr) @@ -6599,7 +6600,7 @@ Commit - Int64 + Int64 (XLogRecPtr) @@ -6609,7 +6610,7 @@ Commit - Int64 + Int64 (TimestampTz) @@ -6644,7 +6645,7 @@ Origin - Int64 + Int64 (XLogRecPtr) @@ -6693,7 +6694,7 @@ Relation - Int32 + Int32 (TransactionId) @@ -6704,11 +6705,11 @@ Relation - Int32 + Int32 (Oid) - ID of the relation. + OID of the relation. @@ -6781,11 +6782,11 @@ Relation - Int32 + Int32 (Oid) - ID of the column's data type. + OID of the column's data type. @@ -6825,7 +6826,7 @@ Type - Int32 + Int32 (TransactionId) @@ -6836,11 +6837,11 @@ Type - Int32 + Int32 (Oid) - ID of the data type. + OID of the data type. @@ -6890,7 +6891,7 @@ Insert - Int32 + Int32 (TransactionId) @@ -6901,11 +6902,11 @@ Insert - Int32 + Int32 (Oid) - ID of the relation corresponding to the ID in the relation + OID of the relation corresponding to the ID in the relation message. @@ -6957,7 +6958,7 @@ Update - Int32 + Int32 (TransactionId) @@ -6968,11 +6969,11 @@ Update - Int32 + Int32 (Oid) - ID of the relation corresponding to the ID in the relation + OID of the relation corresponding to the ID in the relation message. @@ -7071,7 +7072,7 @@ Delete - Int32 + Int32 (TransactionId) @@ -7082,11 +7083,11 @@ Delete - Int32 + Int32 (Oid) - ID of the relation corresponding to the ID in the relation + OID of the relation corresponding to the ID in the relation message. @@ -7160,7 +7161,7 @@ Truncate - Int32 + Int32 (TransactionId) @@ -7192,11 +7193,11 @@ Truncate - Int32 + Int32 (Oid) - ID of the relation corresponding to the ID in the relation + OID of the relation corresponding to the ID in the relation message. This field is repeated for each relation. @@ -7238,7 +7239,7 @@ Stream Start - Int32 + Int32 (TransactionId) @@ -7307,7 +7308,7 @@ Stream Commit - Int32 + Int32 (TransactionId) @@ -7317,17 +7318,17 @@ Stream Commit - Int8 + Int8(0) - Flags; currently unused (must be 0). + Flags; currently unused. - Int64 + Int64 (XLogRecPtr) @@ -7337,7 +7338,7 @@ Stream Commit - Int64 + Int64 (XLogRecPtr) @@ -7347,7 +7348,7 @@ Stream Commit - Int64 + Int64 (TimestampTz) @@ -7382,7 +7383,7 @@ Stream Abort - Int32 + Int32 (TransactionId) @@ -7392,7 +7393,7 @@ Stream Abort - Int32 + Int32 (TransactionId) @@ -7432,21 +7433,27 @@ are available since protocol version 3. -Int64 + + Int64 (XLogRecPtr) + The LSN of the prepare. -Int64 + + Int64 (XLogRecPtr) + The end LSN of the prepared transaction. -Int64 + + Int64 (TimestampTz) + Prepare timestamp of the transaction. The value is in number of microseconds since PostgreSQL epoch (2000-01-01). @@ -7454,7 +7461,9 @@ are available since protocol version 3. -Int32 + + Int32 (TransactionId) + Xid of the transaction. @@ -7489,28 +7498,36 @@ are available since protocol version 3. -Int8 + + Int8(0) + - Flags; currently unused (must be 0). + Flags; currently unused. -Int64 + + Int64 (XLogRecPtr) + The LSN of the prepare. -Int64 + + Int64 (XLogRecPtr) + The end LSN of the prepared transaction. -Int64 + + Int64 (TimestampTz) + Prepare timestamp of the transaction. The value is in number of microseconds since PostgreSQL epoch (2000-01-01). @@ -7518,7 +7535,9 @@ are available since protocol version 3. -Int32 + + Int32 (TransactionId) + Xid of the transaction. @@ -7553,28 +7572,36 @@ are available since protocol version 3. -Int8 + + Int8(0) + - Flags; currently unused (must be 0). + Flags; currently unused. -Int64 + + Int64 (XLogRecPtr) + The LSN of the commit prepared. -Int64 + + Int64 (XLogRecPtr) + The end LSN of the commit prepared transaction. -Int64 + + Int64 (TimestampTz) + Commit timestamp of the transaction. The value is in number of microseconds since PostgreSQL epoch (2000-01-01). @@ -7582,7 +7609,9 @@ are available since protocol version 3. -Int32 + + Int32 (TransactionId) + Xid of the transaction. @@ -7617,28 +7646,36 @@ are available since protocol version 3. -Int8 + + Int8(0) + - Flags; currently unused (must be 0). + Flags; currently unused. -Int64 + + Int64 (XLogRecPtr) + The end LSN of the prepared transaction. -Int64 + + Int64 (XLogRecPtr) + The end LSN of the rollback prepared transaction. -Int64 + + Int64 (TimestampTz) + Prepare timestamp of the transaction. The value is in number of microseconds since PostgreSQL epoch (2000-01-01). @@ -7646,7 +7683,9 @@ are available since protocol version 3. -Int64 + + Int64 (TimestampTz) + Rollback timestamp of the transaction. The value is in number of microseconds since PostgreSQL epoch (2000-01-01). @@ -7654,7 +7693,9 @@ are available since protocol version 3. -Int32 + + Int32 (TransactionId) + Xid of the transaction.