PostgreSQL Source Code  git master
logicalproto.h
Go to the documentation of this file.
1 /*-------------------------------------------------------------------------
2  *
3  * logicalproto.h
4  * logical replication protocol
5  *
6  * Copyright (c) 2015-2022, PostgreSQL Global Development Group
7  *
8  * IDENTIFICATION
9  * src/include/replication/logicalproto.h
10  *
11  *-------------------------------------------------------------------------
12  */
13 #ifndef LOGICAL_PROTO_H
14 #define LOGICAL_PROTO_H
15 
16 #include "access/xact.h"
17 #include "executor/tuptable.h"
19 #include "utils/rel.h"
20 
21 /*
22  * Protocol capabilities
23  *
24  * LOGICALREP_PROTO_VERSION_NUM is our native protocol.
25  * LOGICALREP_PROTO_MAX_VERSION_NUM is the greatest version we can support.
26  * LOGICALREP_PROTO_MIN_VERSION_NUM is the oldest version we
27  * have backwards compatibility for. The client requests protocol version at
28  * connect time.
29  *
30  * LOGICALREP_PROTO_STREAM_VERSION_NUM is the minimum protocol version with
31  * support for streaming large transactions. Introduced in PG14.
32  *
33  * LOGICALREP_PROTO_TWOPHASE_VERSION_NUM is the minimum protocol version with
34  * support for two-phase commit decoding (at prepare time). Introduced in PG15.
35  */
36 #define LOGICALREP_PROTO_MIN_VERSION_NUM 1
37 #define LOGICALREP_PROTO_VERSION_NUM 1
38 #define LOGICALREP_PROTO_STREAM_VERSION_NUM 2
39 #define LOGICALREP_PROTO_TWOPHASE_VERSION_NUM 3
40 #define LOGICALREP_PROTO_MAX_VERSION_NUM LOGICALREP_PROTO_TWOPHASE_VERSION_NUM
41 
42 /*
43  * Logical message types
44  *
45  * Used by logical replication wire protocol.
46  *
47  * Note: though this is an enum, the values are used to identify message types
48  * in logical replication protocol, which uses a single byte to identify a
49  * message type. Hence the values should be single-byte wide and preferably
50  * human-readable characters.
51  */
52 typedef enum LogicalRepMsgType
53 {
74 
75 /*
76  * This struct stores a tuple received via logical replication.
77  * Keep in mind that the columns correspond to the *remote* table.
78  */
79 typedef struct LogicalRepTupleData
80 {
81  /* Array of StringInfos, one per column; some may be unused */
83  /* Array of markers for null/unchanged/text/binary, one per column */
84  char *colstatus;
85  /* Length of above arrays */
86  int ncols;
88 
89 /* Possible values for LogicalRepTupleData.colstatus[colnum] */
90 /* These values are also used in the on-the-wire protocol */
91 #define LOGICALREP_COLUMN_NULL 'n'
92 #define LOGICALREP_COLUMN_UNCHANGED 'u'
93 #define LOGICALREP_COLUMN_TEXT 't'
94 #define LOGICALREP_COLUMN_BINARY 'b' /* added in PG14 */
95 
97 
98 /* Relation information */
99 typedef struct LogicalRepRelation
100 {
101  /* Info coming from the remote side. */
102  LogicalRepRelId remoteid; /* unique id of the relation */
103  char *nspname; /* schema name */
104  char *relname; /* relation name */
105  int natts; /* number of columns */
106  char **attnames; /* column names */
107  Oid *atttyps; /* column types */
108  char replident; /* replica identity */
109  char relkind; /* remote relation kind */
110  Bitmapset *attkeys; /* Bitmap of key columns */
112 
113 /* Type mapping info */
114 typedef struct LogicalRepTyp
115 {
116  Oid remoteid; /* unique id of the remote type */
117  char *nspname; /* schema name of remote type */
118  char *typname; /* name of the remote type */
120 
121 /* Transaction info */
122 typedef struct LogicalRepBeginData
123 {
128 
129 typedef struct LogicalRepCommitData
130 {
135 
136 /*
137  * Prepared transaction protocol information for begin_prepare, and prepare.
138  */
140 {
145  char gid[GIDSIZE];
147 
148 /*
149  * Prepared transaction protocol information for commit prepared.
150  */
152 {
157  char gid[GIDSIZE];
159 
160 /*
161  * Rollback Prepared transaction protocol information. The prepare information
162  * prepare_end_lsn and prepare_time are used to check if the downstream has
163  * received this prepared transaction in which case it can apply the rollback,
164  * otherwise, it can skip the rollback operation. The gid alone is not
165  * sufficient because the downstream node can have a prepared transaction with
166  * same identifier.
167  */
169 {
175  char gid[GIDSIZE];
177 
178 extern void logicalrep_write_begin(StringInfo out, ReorderBufferTXN *txn);
179 extern void logicalrep_read_begin(StringInfo in,
180  LogicalRepBeginData *begin_data);
182  XLogRecPtr commit_lsn);
183 extern void logicalrep_read_commit(StringInfo in,
184  LogicalRepCommitData *commit_data);
187  LogicalRepPreparedTxnData *begin_data);
189  XLogRecPtr prepare_lsn);
190 extern void logicalrep_read_prepare(StringInfo in,
191  LogicalRepPreparedTxnData *prepare_data);
193  XLogRecPtr commit_lsn);
195  LogicalRepCommitPreparedTxnData *prepare_data);
197  XLogRecPtr prepare_end_lsn,
198  TimestampTz prepare_time);
200  LogicalRepRollbackPreparedTxnData *rollback_data);
202  XLogRecPtr prepare_lsn);
204  LogicalRepPreparedTxnData *prepare_data);
205 
206 extern void logicalrep_write_origin(StringInfo out, const char *origin,
207  XLogRecPtr origin_lsn);
208 extern char *logicalrep_read_origin(StringInfo in, XLogRecPtr *origin_lsn);
210  Relation rel,
211  TupleTableSlot *newslot,
212  bool binary, Bitmapset *columns);
215  Relation rel,
216  TupleTableSlot *oldslot,
217  TupleTableSlot *newslot, bool binary, Bitmapset *columns);
219  bool *has_oldtuple, LogicalRepTupleData *oldtup,
220  LogicalRepTupleData *newtup);
222  Relation rel, TupleTableSlot *oldtuple,
223  bool binary);
225  LogicalRepTupleData *oldtup);
227  int nrelids, Oid relids[],
228  bool cascade, bool restart_seqs);
230  bool *cascade, bool *restart_seqs);
232  bool transactional, const char *prefix, Size sz, const char *message);
233 extern void logicalrep_write_rel(StringInfo out, TransactionId xid,
234  Relation rel, Bitmapset *columns);
236 extern void logicalrep_write_typ(StringInfo out, TransactionId xid,
237  Oid typoid);
238 extern void logicalrep_read_typ(StringInfo out, LogicalRepTyp *ltyp);
240  bool first_segment);
242  bool *first_segment);
245  XLogRecPtr commit_lsn);
247  LogicalRepCommitData *commit_data);
249  TransactionId subxid);
251  TransactionId *subxid);
253 
254 #endif /* LOGICAL_PROTO_H */
unsigned int uint32
Definition: c.h:441
uint32 TransactionId
Definition: c.h:587
size_t Size
Definition: c.h:540
int64 TimestampTz
Definition: timestamp.h:39
void logicalrep_read_commit(StringInfo in, LogicalRepCommitData *commit_data)
Definition: proto.c:109
LogicalRepRelId logicalrep_read_delete(StringInfo in, LogicalRepTupleData *oldtup)
Definition: proto.c:563
void logicalrep_write_commit(StringInfo out, ReorderBufferTXN *txn, XLogRecPtr commit_lsn)
Definition: proto.c:89
void logicalrep_write_rollback_prepared(StringInfo out, ReorderBufferTXN *txn, XLogRecPtr prepare_end_lsn, TimestampTz prepare_time)
Definition: proto.c:304
struct LogicalRepRelation LogicalRepRelation
void logicalrep_read_rollback_prepared(StringInfo in, LogicalRepRollbackPreparedTxnData *rollback_data)
Definition: proto.c:336
void logicalrep_write_origin(StringInfo out, const char *origin, XLogRecPtr origin_lsn)
Definition: proto.c:385
void logicalrep_read_begin_prepare(StringInfo in, LogicalRepPreparedTxnData *begin_data)
Definition: proto.c:145
void logicalrep_write_delete(StringInfo out, TransactionId xid, Relation rel, TupleTableSlot *oldtuple, bool binary)
Definition: proto.c:533
struct LogicalRepCommitPreparedTxnData LogicalRepCommitPreparedTxnData
void logicalrep_read_typ(StringInfo out, LogicalRepTyp *ltyp)
Definition: proto.c:755
struct LogicalRepTupleData LogicalRepTupleData
List * logicalrep_read_truncate(StringInfo in, bool *cascade, bool *restart_seqs)
Definition: proto.c:617
char * logicalrep_message_type(LogicalRepMsgType action)
Definition: proto.c:1197
struct LogicalRepCommitData LogicalRepCommitData
void logicalrep_write_rel(StringInfo out, TransactionId xid, Relation rel, Bitmapset *columns)
Definition: proto.c:669
LogicalRepRelId logicalrep_read_update(StringInfo in, bool *has_oldtuple, LogicalRepTupleData *oldtup, LogicalRepTupleData *newtup)
Definition: proto.c:492
struct LogicalRepTyp LogicalRepTyp
void logicalrep_write_message(StringInfo out, TransactionId xid, XLogRecPtr lsn, bool transactional, const char *prefix, Size sz, const char *message)
Definition: proto.c:642
void logicalrep_write_update(StringInfo out, TransactionId xid, Relation rel, TupleTableSlot *oldslot, TupleTableSlot *newslot, bool binary, Bitmapset *columns)
Definition: proto.c:458
TransactionId logicalrep_read_stream_commit(StringInfo out, LogicalRepCommitData *commit_data)
Definition: proto.c:1142
struct LogicalRepBeginData LogicalRepBeginData
void logicalrep_write_prepare(StringInfo out, ReorderBufferTXN *txn, XLogRecPtr prepare_lsn)
Definition: proto.c:198
void logicalrep_read_begin(StringInfo in, LogicalRepBeginData *begin_data)
Definition: proto.c:74
void logicalrep_write_insert(StringInfo out, TransactionId xid, Relation rel, TupleTableSlot *newslot, bool binary, Bitmapset *columns)
Definition: proto.c:414
void logicalrep_write_typ(StringInfo out, TransactionId xid, Oid typoid)
Definition: proto.c:724
void logicalrep_write_truncate(StringInfo out, TransactionId xid, int nrelids, Oid relids[], bool cascade, bool restart_seqs)
Definition: proto.c:585
LogicalRepMsgType
Definition: logicalproto.h:53
@ LOGICAL_REP_MSG_INSERT
Definition: logicalproto.h:57
@ LOGICAL_REP_MSG_TRUNCATE
Definition: logicalproto.h:60
@ LOGICAL_REP_MSG_STREAM_STOP
Definition: logicalproto.h:69
@ LOGICAL_REP_MSG_BEGIN
Definition: logicalproto.h:54
@ LOGICAL_REP_MSG_STREAM_PREPARE
Definition: logicalproto.h:72
@ LOGICAL_REP_MSG_STREAM_ABORT
Definition: logicalproto.h:71
@ LOGICAL_REP_MSG_BEGIN_PREPARE
Definition: logicalproto.h:64
@ LOGICAL_REP_MSG_STREAM_START
Definition: logicalproto.h:68
@ LOGICAL_REP_MSG_COMMIT
Definition: logicalproto.h:55
@ LOGICAL_REP_MSG_PREPARE
Definition: logicalproto.h:65
@ LOGICAL_REP_MSG_RELATION
Definition: logicalproto.h:61
@ LOGICAL_REP_MSG_MESSAGE
Definition: logicalproto.h:63
@ LOGICAL_REP_MSG_ROLLBACK_PREPARED
Definition: logicalproto.h:67
@ LOGICAL_REP_MSG_COMMIT_PREPARED
Definition: logicalproto.h:66
@ LOGICAL_REP_MSG_TYPE
Definition: logicalproto.h:62
@ LOGICAL_REP_MSG_DELETE
Definition: logicalproto.h:59
@ LOGICAL_REP_MSG_STREAM_COMMIT
Definition: logicalproto.h:70
@ LOGICAL_REP_MSG_ORIGIN
Definition: logicalproto.h:56
@ LOGICAL_REP_MSG_UPDATE
Definition: logicalproto.h:58
void logicalrep_write_begin(StringInfo out, ReorderBufferTXN *txn)
Definition: proto.c:60
void logicalrep_read_commit_prepared(StringInfo in, LogicalRepCommitPreparedTxnData *prepare_data)
Definition: proto.c:278
struct LogicalRepPreparedTxnData LogicalRepPreparedTxnData
struct LogicalRepRollbackPreparedTxnData LogicalRepRollbackPreparedTxnData
LogicalRepRelation * logicalrep_read_rel(StringInfo in)
Definition: proto.c:699
void logicalrep_write_commit_prepared(StringInfo out, ReorderBufferTXN *txn, XLogRecPtr commit_lsn)
Definition: proto.c:248
void logicalrep_write_stream_commit(StringInfo out, ReorderBufferTXN *txn, XLogRecPtr commit_lsn)
Definition: proto.c:1117
void logicalrep_write_stream_prepare(StringInfo out, ReorderBufferTXN *txn, XLogRecPtr prepare_lsn)
Definition: proto.c:364
void logicalrep_write_stream_abort(StringInfo out, TransactionId xid, TransactionId subxid)
Definition: proto.c:1168
void logicalrep_read_stream_abort(StringInfo in, TransactionId *xid, TransactionId *subxid)
Definition: proto.c:1184
void logicalrep_write_begin_prepare(StringInfo out, ReorderBufferTXN *txn)
Definition: proto.c:127
void logicalrep_read_stream_prepare(StringInfo in, LogicalRepPreparedTxnData *prepare_data)
Definition: proto.c:376
void logicalrep_write_stream_start(StringInfo out, TransactionId xid, bool first_segment)
Definition: proto.c:1074
uint32 LogicalRepRelId
Definition: logicalproto.h:96
char * logicalrep_read_origin(StringInfo in, XLogRecPtr *origin_lsn)
Definition: proto.c:401
LogicalRepRelId logicalrep_read_insert(StringInfo in, LogicalRepTupleData *newtup)
Definition: proto.c:436
void logicalrep_read_prepare(StringInfo in, LogicalRepPreparedTxnData *prepare_data)
Definition: proto.c:239
void logicalrep_write_stream_stop(StringInfo out)
Definition: proto.c:1108
TransactionId logicalrep_read_stream_start(StringInfo in, bool *first_segment)
Definition: proto.c:1092
unsigned int Oid
Definition: postgres_ext.h:31
Definition: pg_list.h:51
XLogRecPtr final_lsn
Definition: logicalproto.h:124
TransactionId xid
Definition: logicalproto.h:126
TimestampTz committime
Definition: logicalproto.h:125
TimestampTz committime
Definition: logicalproto.h:133
LogicalRepRelId remoteid
Definition: logicalproto.h:102
Bitmapset * attkeys
Definition: logicalproto.h:110
StringInfoData * colvalues
Definition: logicalproto.h:82
#define GIDSIZE
Definition: xact.h:31
uint64 XLogRecPtr
Definition: xlogdefs.h:21