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-2024, 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  * LOGICALREP_PROTO_STREAM_PARALLEL_VERSION_NUM is the minimum protocol version
37  * where we support applying large streaming transactions in parallel.
38  * Introduced in PG16.
39  */
40 #define LOGICALREP_PROTO_MIN_VERSION_NUM 1
41 #define LOGICALREP_PROTO_VERSION_NUM 1
42 #define LOGICALREP_PROTO_STREAM_VERSION_NUM 2
43 #define LOGICALREP_PROTO_TWOPHASE_VERSION_NUM 3
44 #define LOGICALREP_PROTO_STREAM_PARALLEL_VERSION_NUM 4
45 #define LOGICALREP_PROTO_MAX_VERSION_NUM LOGICALREP_PROTO_STREAM_PARALLEL_VERSION_NUM
46 
47 /*
48  * Logical message types
49  *
50  * Used by logical replication wire protocol.
51  *
52  * Note: though this is an enum, the values are used to identify message types
53  * in logical replication protocol, which uses a single byte to identify a
54  * message type. Hence the values should be single-byte wide and preferably
55  * human-readable characters.
56  */
57 typedef enum LogicalRepMsgType
58 {
79 
80 /*
81  * This struct stores a tuple received via logical replication.
82  * Keep in mind that the columns correspond to the *remote* table.
83  */
84 typedef struct LogicalRepTupleData
85 {
86  /* Array of StringInfos, one per column; some may be unused */
88  /* Array of markers for null/unchanged/text/binary, one per column */
89  char *colstatus;
90  /* Length of above arrays */
91  int ncols;
93 
94 /* Possible values for LogicalRepTupleData.colstatus[colnum] */
95 /* These values are also used in the on-the-wire protocol */
96 #define LOGICALREP_COLUMN_NULL 'n'
97 #define LOGICALREP_COLUMN_UNCHANGED 'u'
98 #define LOGICALREP_COLUMN_TEXT 't'
99 #define LOGICALREP_COLUMN_BINARY 'b' /* added in PG14 */
100 
102 
103 /* Relation information */
104 typedef struct LogicalRepRelation
105 {
106  /* Info coming from the remote side. */
107  LogicalRepRelId remoteid; /* unique id of the relation */
108  char *nspname; /* schema name */
109  char *relname; /* relation name */
110  int natts; /* number of columns */
111  char **attnames; /* column names */
112  Oid *atttyps; /* column types */
113  char replident; /* replica identity */
114  char relkind; /* remote relation kind */
115  Bitmapset *attkeys; /* Bitmap of key columns */
117 
118 /* Type mapping info */
119 typedef struct LogicalRepTyp
120 {
121  Oid remoteid; /* unique id of the remote type */
122  char *nspname; /* schema name of remote type */
123  char *typname; /* name of the remote type */
125 
126 /* Transaction info */
127 typedef struct LogicalRepBeginData
128 {
133 
134 typedef struct LogicalRepCommitData
135 {
140 
141 /*
142  * Prepared transaction protocol information for begin_prepare, and prepare.
143  */
145 {
150  char gid[GIDSIZE];
152 
153 /*
154  * Prepared transaction protocol information for commit prepared.
155  */
157 {
162  char gid[GIDSIZE];
164 
165 /*
166  * Rollback Prepared transaction protocol information. The prepare information
167  * prepare_end_lsn and prepare_time are used to check if the downstream has
168  * received this prepared transaction in which case it can apply the rollback,
169  * otherwise, it can skip the rollback operation. The gid alone is not
170  * sufficient because the downstream node can have a prepared transaction with
171  * same identifier.
172  */
174 {
180  char gid[GIDSIZE];
182 
183 /*
184  * Transaction protocol information for stream abort.
185  */
187 {
193 
194 extern void logicalrep_write_begin(StringInfo out, ReorderBufferTXN *txn);
195 extern void logicalrep_read_begin(StringInfo in,
196  LogicalRepBeginData *begin_data);
198  XLogRecPtr commit_lsn);
199 extern void logicalrep_read_commit(StringInfo in,
200  LogicalRepCommitData *commit_data);
203  LogicalRepPreparedTxnData *begin_data);
205  XLogRecPtr prepare_lsn);
206 extern void logicalrep_read_prepare(StringInfo in,
207  LogicalRepPreparedTxnData *prepare_data);
209  XLogRecPtr commit_lsn);
211  LogicalRepCommitPreparedTxnData *prepare_data);
213  XLogRecPtr prepare_end_lsn,
214  TimestampTz prepare_time);
216  LogicalRepRollbackPreparedTxnData *rollback_data);
218  XLogRecPtr prepare_lsn);
220  LogicalRepPreparedTxnData *prepare_data);
221 
222 extern void logicalrep_write_origin(StringInfo out, const char *origin,
223  XLogRecPtr origin_lsn);
224 extern char *logicalrep_read_origin(StringInfo in, XLogRecPtr *origin_lsn);
226  Relation rel,
227  TupleTableSlot *newslot,
228  bool binary, Bitmapset *columns);
231  Relation rel,
232  TupleTableSlot *oldslot,
233  TupleTableSlot *newslot, bool binary, Bitmapset *columns);
235  bool *has_oldtuple, LogicalRepTupleData *oldtup,
236  LogicalRepTupleData *newtup);
238  Relation rel, TupleTableSlot *oldslot,
239  bool binary, Bitmapset *columns);
241  LogicalRepTupleData *oldtup);
243  int nrelids, Oid relids[],
244  bool cascade, bool restart_seqs);
246  bool *cascade, bool *restart_seqs);
248  bool transactional, const char *prefix, Size sz, const char *message);
249 extern void logicalrep_write_rel(StringInfo out, TransactionId xid,
250  Relation rel, Bitmapset *columns);
252 extern void logicalrep_write_typ(StringInfo out, TransactionId xid,
253  Oid typoid);
254 extern void logicalrep_read_typ(StringInfo in, LogicalRepTyp *ltyp);
256  bool first_segment);
258  bool *first_segment);
261  XLogRecPtr commit_lsn);
263  LogicalRepCommitData *commit_data);
265  TransactionId subxid,
266  XLogRecPtr abort_lsn,
267  TimestampTz abort_time,
268  bool write_abort_info);
270  LogicalRepStreamAbortData *abort_data,
271  bool read_abort_info);
273 
274 #endif /* LOGICAL_PROTO_H */
unsigned int uint32
Definition: c.h:493
uint32 TransactionId
Definition: c.h:639
size_t Size
Definition: c.h:592
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:564
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
const char * logicalrep_message_type(LogicalRepMsgType action)
Definition: proto.c:1217
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_stream_abort(StringInfo out, TransactionId xid, TransactionId subxid, XLogRecPtr abort_lsn, TimestampTz abort_time, bool write_abort_info)
Definition: proto.c:1166
struct LogicalRepCommitPreparedTxnData LogicalRepCommitPreparedTxnData
struct LogicalRepTupleData LogicalRepTupleData
List * logicalrep_read_truncate(StringInfo in, bool *cascade, bool *restart_seqs)
Definition: proto.c:618
void logicalrep_read_typ(StringInfo in, LogicalRepTyp *ltyp)
Definition: proto.c:756
struct LogicalRepCommitData LogicalRepCommitData
void logicalrep_write_rel(StringInfo out, TransactionId xid, Relation rel, Bitmapset *columns)
Definition: proto.c:670
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:643
void logicalrep_write_update(StringInfo out, TransactionId xid, Relation rel, TupleTableSlot *oldslot, TupleTableSlot *newslot, bool binary, Bitmapset *columns)
Definition: proto.c:458
struct LogicalRepStreamAbortData LogicalRepStreamAbortData
void logicalrep_read_stream_abort(StringInfo in, LogicalRepStreamAbortData *abort_data, bool read_abort_info)
Definition: proto.c:1192
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:725
void logicalrep_write_truncate(StringInfo out, TransactionId xid, int nrelids, Oid relids[], bool cascade, bool restart_seqs)
Definition: proto.c:586
LogicalRepMsgType
Definition: logicalproto.h:58
@ LOGICAL_REP_MSG_INSERT
Definition: logicalproto.h:62
@ LOGICAL_REP_MSG_TRUNCATE
Definition: logicalproto.h:65
@ LOGICAL_REP_MSG_STREAM_STOP
Definition: logicalproto.h:74
@ LOGICAL_REP_MSG_BEGIN
Definition: logicalproto.h:59
@ LOGICAL_REP_MSG_STREAM_PREPARE
Definition: logicalproto.h:77
@ LOGICAL_REP_MSG_STREAM_ABORT
Definition: logicalproto.h:76
@ LOGICAL_REP_MSG_BEGIN_PREPARE
Definition: logicalproto.h:69
@ LOGICAL_REP_MSG_STREAM_START
Definition: logicalproto.h:73
@ LOGICAL_REP_MSG_COMMIT
Definition: logicalproto.h:60
@ LOGICAL_REP_MSG_PREPARE
Definition: logicalproto.h:70
@ LOGICAL_REP_MSG_RELATION
Definition: logicalproto.h:66
@ LOGICAL_REP_MSG_MESSAGE
Definition: logicalproto.h:68
@ LOGICAL_REP_MSG_ROLLBACK_PREPARED
Definition: logicalproto.h:72
@ LOGICAL_REP_MSG_COMMIT_PREPARED
Definition: logicalproto.h:71
@ LOGICAL_REP_MSG_TYPE
Definition: logicalproto.h:67
@ LOGICAL_REP_MSG_DELETE
Definition: logicalproto.h:64
@ LOGICAL_REP_MSG_STREAM_COMMIT
Definition: logicalproto.h:75
@ LOGICAL_REP_MSG_ORIGIN
Definition: logicalproto.h:61
@ LOGICAL_REP_MSG_UPDATE
Definition: logicalproto.h:63
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
void logicalrep_write_delete(StringInfo out, TransactionId xid, Relation rel, TupleTableSlot *oldslot, bool binary, Bitmapset *columns)
Definition: proto.c:533
struct LogicalRepRollbackPreparedTxnData LogicalRepRollbackPreparedTxnData
LogicalRepRelation * logicalrep_read_rel(StringInfo in)
Definition: proto.c:700
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:1112
void logicalrep_write_stream_prepare(StringInfo out, ReorderBufferTXN *txn, XLogRecPtr prepare_lsn)
Definition: proto.c:364
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:1069
uint32 LogicalRepRelId
Definition: logicalproto.h:101
char * logicalrep_read_origin(StringInfo in, XLogRecPtr *origin_lsn)
Definition: proto.c:401
TransactionId logicalrep_read_stream_commit(StringInfo in, LogicalRepCommitData *commit_data)
Definition: proto.c:1137
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:1103
TransactionId logicalrep_read_stream_start(StringInfo in, bool *first_segment)
Definition: proto.c:1087
unsigned int Oid
Definition: postgres_ext.h:31
Definition: pg_list.h:54
XLogRecPtr final_lsn
Definition: logicalproto.h:129
TransactionId xid
Definition: logicalproto.h:131
TimestampTz committime
Definition: logicalproto.h:130
TimestampTz committime
Definition: logicalproto.h:138
LogicalRepRelId remoteid
Definition: logicalproto.h:107
Bitmapset * attkeys
Definition: logicalproto.h:115
StringInfoData * colvalues
Definition: logicalproto.h:87
#define GIDSIZE
Definition: xact.h:31
uint64 XLogRecPtr
Definition: xlogdefs.h:21