Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commit641dd16

Browse files
committed
Move description of libpqwalreceiver hooks out of the replication's README
src/backend/replication/README includes since32bc08b a basicdescription of the WAL receiver hooks available in walreceiver.h for amodule like libpqwalreceiver, but the README has never been updated toreflect changes done to the hooks, so the contents of the README haverotten with the time. This commit moves the description from the READMEto walreceiver.h, where it will be hard to miss that a descriptionupdate or addition is needed depending on the modifications done to thehooks.Each hook now includes a description of what it does in walreceiver.h,and the replication's README mentions walreceiver.h.Thanks also to Amit Kapila for the discussion.Author: Michael PaquierReviewed-by: Peter EisentrautDiscussion:https://postgr.es/m/20200502024606.GA471944@paquier.xyz
1 parent4315e8c commit641dd16

File tree

2 files changed

+132
-33
lines changed

2 files changed

+132
-33
lines changed

‎src/backend/replication/README

Lines changed: 2 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -8,33 +8,8 @@ the primary server, receiving WAL files and sending messages, is loaded
88
dynamically to avoid having to link the main server binary with libpq.
99
The dynamically loaded module is in libpqwalreceiver subdirectory.
1010

11-
The dynamically loaded module implements four functions:
12-
13-
14-
bool walrcv_connect(char *conninfo, XLogRecPtr startpoint)
15-
16-
Establish connection to the primary, and starts streaming from 'startpoint'.
17-
Returns true on success.
18-
19-
int walrcv_receive(char **buffer, pgsocket *wait_fd)
20-
21-
Retrieve any message available without blocking through the
22-
connection. If a message was successfully read, returns its
23-
length. If the connection is closed, returns -1. Otherwise returns 0
24-
to indicate that no data is available, and sets *wait_fd to a socket
25-
descriptor which can be waited on before trying again. On success, a
26-
pointer to the message payload is stored in *buffer. The returned
27-
buffer is valid until the next call to walrcv_* functions, and the
28-
caller should not attempt to free it.
29-
30-
void walrcv_send(const char *buffer, int nbytes)
31-
32-
Send a message to XLOG stream.
33-
34-
void walrcv_disconnect(void);
35-
36-
Disconnect.
37-
11+
The dynamically loaded module implements a set of functions with details
12+
about each one of them provided in src/include/replication/walreceiver.h.
3813

3914
This API should be considered internal at the moment, but we could open it
4015
up for 3rd party replacements of libpqwalreceiver in the future, allowing

‎src/include/replication/walreceiver.h

Lines changed: 130 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -213,39 +213,163 @@ typedef struct WalRcvExecResult
213213
TupleDesctupledesc;
214214
}WalRcvExecResult;
215215

216-
/* libpqwalreceiver hooks */
217-
typedefWalReceiverConn*(*walrcv_connect_fn) (constchar*conninfo,boollogical,
216+
/* WAL receiver - libpqwalreceiver hooks */
217+
218+
/*
219+
* walrcv_connect_fn
220+
*
221+
* Establish connection to a cluster. 'logical' is true if the
222+
* connection is logical, and false if the connection is physical.
223+
* 'appname' is a name associated to the connection, to use for example
224+
* with fallback_application_name or application_name. Returns the
225+
* details about the connection established, as defined by
226+
* WalReceiverConn for each WAL receiver module. On error, NULL is
227+
* returned with 'err' including the error generated.
228+
*/
229+
typedefWalReceiverConn*(*walrcv_connect_fn) (constchar*conninfo,
230+
boollogical,
218231
constchar*appname,
219232
char**err);
233+
234+
/*
235+
* walrcv_check_conninfo_fn
236+
*
237+
* Parse and validate the connection string given as of 'conninfo'.
238+
*/
220239
typedefvoid (*walrcv_check_conninfo_fn) (constchar*conninfo);
240+
241+
/*
242+
* walrcv_get_conninfo_fn
243+
*
244+
* Returns a user-displayable conninfo string. Note that any
245+
* security-sensitive fields should be obfuscated.
246+
*/
221247
typedefchar*(*walrcv_get_conninfo_fn) (WalReceiverConn*conn);
248+
249+
/*
250+
* walrcv_get_senderinfo_fn
251+
*
252+
* Provide information of the WAL sender this WAL receiver is connected
253+
* to, as of 'sender_host' for the host of the sender and 'sender_port'
254+
* for its port.
255+
*/
222256
typedefvoid (*walrcv_get_senderinfo_fn) (WalReceiverConn*conn,
223257
char**sender_host,
224258
int*sender_port);
259+
260+
/*
261+
* walrcv_identify_system_fn
262+
*
263+
* Run IDENTIFY_SYSTEM on the cluster connected to and validate the
264+
* identity of the cluster. Returns the system ID of the cluster
265+
* connected to. 'primary_tli' is the timeline ID of the sender.
266+
*/
225267
typedefchar*(*walrcv_identify_system_fn) (WalReceiverConn*conn,
226268
TimeLineID*primary_tli);
269+
270+
/*
271+
* walrcv_server_version_fn
272+
*
273+
* Returns the version number of the cluster connected to.
274+
*/
227275
typedefint (*walrcv_server_version_fn) (WalReceiverConn*conn);
276+
277+
/*
278+
* walrcv_readtimelinehistoryfile_fn
279+
*
280+
* Fetch from cluster the timeline history file for timeline 'tli'.
281+
* Returns the name of the timeline history file as of 'filename', its
282+
* contents as of 'content' and its 'size'.
283+
*/
228284
typedefvoid (*walrcv_readtimelinehistoryfile_fn) (WalReceiverConn*conn,
229285
TimeLineIDtli,
230286
char**filename,
231-
char**content,int*size);
287+
char**content,
288+
int*size);
289+
290+
/*
291+
* walrcv_startstreaming_fn
292+
*
293+
* Start streaming WAL data from given streaming options. Returns true
294+
* if the connection has switched successfully to copy-both mode and false
295+
* if the server received the command and executed it successfully, but
296+
* didn't switch to copy-mode.
297+
*/
232298
typedefbool (*walrcv_startstreaming_fn) (WalReceiverConn*conn,
233299
constWalRcvStreamOptions*options);
300+
301+
/*
302+
* walrcv_endstreaming_fn
303+
*
304+
* Stop streaming of WAL data. Returns the next timeline ID of the cluster
305+
* connected to in 'next_tli', or 0 if there was no report.
306+
*/
234307
typedefvoid (*walrcv_endstreaming_fn) (WalReceiverConn*conn,
235308
TimeLineID*next_tli);
236-
typedefint (*walrcv_receive_fn) (WalReceiverConn*conn,char**buffer,
309+
310+
/*
311+
* walrcv_receive_fn
312+
*
313+
* Receive a message available from the WAL stream. 'buffer' is a pointer
314+
* to a buffer holding the message received. Returns the length of the data,
315+
* 0 if no data is available yet ('wait_fd' is a socket descriptor which can
316+
* be waited on before a retry), and -1 if the cluster ended the COPY.
317+
*/
318+
typedefint (*walrcv_receive_fn) (WalReceiverConn*conn,
319+
char**buffer,
237320
pgsocket*wait_fd);
238-
typedefvoid (*walrcv_send_fn) (WalReceiverConn*conn,constchar*buffer,
321+
322+
/*
323+
* walrcv_send_fn
324+
*
325+
* Send a message of size 'nbytes' to the WAL stream with 'buffer' as
326+
* contents.
327+
*/
328+
typedefvoid (*walrcv_send_fn) (WalReceiverConn*conn,
329+
constchar*buffer,
239330
intnbytes);
331+
332+
/*
333+
* walrcv_create_slot_fn
334+
*
335+
* Create a new replication slot named 'slotname'. 'temporary' defines
336+
* if the slot is temporary. 'snapshot_action' defines the behavior wanted
337+
* for an exported snapshot (see replication protocol for more details).
338+
* 'lsn' includes the LSN position at which the created slot became
339+
* consistent. Returns the name of the exported snapshot for a logical
340+
* slot, or NULL for a physical slot.
341+
*/
240342
typedefchar*(*walrcv_create_slot_fn) (WalReceiverConn*conn,
241-
constchar*slotname,booltemporary,
343+
constchar*slotname,
344+
booltemporary,
242345
CRSSnapshotActionsnapshot_action,
243346
XLogRecPtr*lsn);
347+
348+
/*
349+
* walrcv_get_backend_pid_fn
350+
*
351+
* Returns the PID of the remote backend process.
352+
*/
244353
typedefpid_t (*walrcv_get_backend_pid_fn) (WalReceiverConn*conn);
354+
355+
/*
356+
* walrcv_exec_fn
357+
*
358+
* Send generic queries (and commands) to the remote cluster. 'nRetTypes'
359+
* is the expected number of returned attributes, and 'retTypes' an array
360+
* including their type OIDs. Returns the status of the execution and
361+
* tuples if any.
362+
*/
245363
typedefWalRcvExecResult*(*walrcv_exec_fn) (WalReceiverConn*conn,
246364
constchar*query,
247365
constintnRetTypes,
248366
constOid*retTypes);
367+
368+
/*
369+
* walrcv_disconnect_fn
370+
*
371+
* Disconnect with the cluster.
372+
*/
249373
typedefvoid (*walrcv_disconnect_fn) (WalReceiverConn*conn);
250374

251375
typedefstructWalReceiverFunctionsType

0 commit comments

Comments
 (0)
[8]ページ先頭
©2009-2025 Movatter.jp