2010-09-20 22:08:53 +02:00
|
|
|
src/backend/replication/README
|
2010-01-20 10:16:24 +01:00
|
|
|
|
|
|
|
Walreceiver - libpqwalreceiver API
|
|
|
|
----------------------------------
|
|
|
|
|
|
|
|
The transport-specific part of walreceiver, responsible for connecting to
|
2011-03-10 14:59:59 +01:00
|
|
|
the primary server, receiving WAL files and sending messages, is loaded
|
|
|
|
dynamically to avoid having to link the main server binary with libpq.
|
|
|
|
The dynamically loaded module is in libpqwalreceiver subdirectory.
|
2010-01-20 10:16:24 +01:00
|
|
|
|
2011-03-10 14:59:59 +01:00
|
|
|
The dynamically loaded module implements four functions:
|
2010-01-20 10:16:24 +01:00
|
|
|
|
|
|
|
|
|
|
|
bool walrcv_connect(char *conninfo, XLogRecPtr startpoint)
|
|
|
|
|
|
|
|
Establish connection to the primary, and starts streaming from 'startpoint'.
|
|
|
|
Returns true on success.
|
|
|
|
|
2016-04-14 19:49:37 +02:00
|
|
|
int walrcv_receive(char **buffer, pgsocket *wait_fd)
|
2016-03-30 03:16:12 +02:00
|
|
|
|
|
|
|
Retrieve any message available without blocking through the
|
|
|
|
connection. If a message was successfully read, returns its
|
|
|
|
length. If the connection is closed, returns -1. Otherwise returns 0
|
2016-04-14 19:49:37 +02:00
|
|
|
to indicate that no data is available, and sets *wait_fd to a socket
|
2016-03-30 03:16:12 +02:00
|
|
|
descriptor which can be waited on before trying again. On success, a
|
|
|
|
pointer to the message payload is stored in *buffer. The returned
|
|
|
|
buffer is valid until the next call to walrcv_* functions, and the
|
|
|
|
caller should not attempt to free it.
|
2010-01-20 10:16:24 +01:00
|
|
|
|
2011-03-10 14:59:59 +01:00
|
|
|
void walrcv_send(const char *buffer, int nbytes)
|
|
|
|
|
|
|
|
Send a message to XLOG stream.
|
|
|
|
|
2010-01-20 10:16:24 +01:00
|
|
|
void walrcv_disconnect(void);
|
|
|
|
|
|
|
|
Disconnect.
|
|
|
|
|
|
|
|
|
|
|
|
This API should be considered internal at the moment, but we could open it
|
|
|
|
up for 3rd party replacements of libpqwalreceiver in the future, allowing
|
2012-08-31 10:30:11 +02:00
|
|
|
pluggable methods for receiving WAL.
|
2010-01-15 10:19:10 +01:00
|
|
|
|
|
|
|
Walreceiver IPC
|
|
|
|
---------------
|
|
|
|
|
|
|
|
When the WAL replay in startup process has reached the end of archived WAL,
|
2015-02-24 13:32:56 +01:00
|
|
|
restorable using restore_command, it starts up the walreceiver process
|
2010-01-15 10:19:10 +01:00
|
|
|
to fetch more WAL (if streaming replication is configured).
|
|
|
|
|
|
|
|
Walreceiver is a postmaster subprocess, so the startup process can't fork it
|
|
|
|
directly. Instead, it sends a signal to postmaster, asking postmaster to launch
|
2014-02-01 04:45:17 +01:00
|
|
|
it. Before that, however, startup process fills in WalRcvData->conninfo
|
|
|
|
and WalRcvData->slotname, and initializes the starting point in
|
|
|
|
WalRcvData->receiveStart.
|
2010-01-15 10:19:10 +01:00
|
|
|
|
|
|
|
As walreceiver receives WAL from the master server, and writes and flushes
|
2016-10-20 17:24:37 +02:00
|
|
|
it to disk (in pg_wal), it updates WalRcvData->receivedUpto and signals
|
2011-03-10 14:59:59 +01:00
|
|
|
the startup process to know how far WAL replay can advance.
|
|
|
|
|
|
|
|
Walreceiver sends information about replication progress to the master server
|
2012-08-31 10:30:11 +02:00
|
|
|
whenever it either writes or flushes new WAL, or the specified interval elapses.
|
2011-03-10 14:59:59 +01:00
|
|
|
This is used for reporting purpose.
|
2010-01-15 10:19:10 +01:00
|
|
|
|
|
|
|
Walsender IPC
|
|
|
|
-------------
|
|
|
|
|
|
|
|
At shutdown, postmaster handles walsender processes differently from regular
|
|
|
|
backends. It waits for regular backends to die before writing the
|
|
|
|
shutdown checkpoint and terminating pgarch and other auxiliary processes, but
|
|
|
|
that's not desirable for walsenders, because we want the standby servers to
|
|
|
|
receive all the WAL, including the shutdown checkpoint, before the master
|
|
|
|
is shut down. Therefore postmaster treats walsenders like the pgarch process,
|
|
|
|
and instructs them to terminate at PM_SHUTDOWN_2 phase, after all regular
|
2011-11-01 19:48:47 +01:00
|
|
|
backends have died and checkpointer has issued the shutdown checkpoint.
|
2010-01-15 10:19:10 +01:00
|
|
|
|
|
|
|
When postmaster accepts a connection, it immediately forks a new process
|
|
|
|
to handle the handshake and authentication, and the process initializes to
|
|
|
|
become a backend. Postmaster doesn't know if the process becomes a regular
|
|
|
|
backend or a walsender process at that time - that's indicated in the
|
|
|
|
connection handshake - so we need some extra signaling to let postmaster
|
|
|
|
identify walsender processes.
|
|
|
|
|
|
|
|
When walsender process starts up, it marks itself as a walsender process in
|
|
|
|
the PMSignal array. That way postmaster can tell it apart from regular
|
|
|
|
backends.
|
|
|
|
|
|
|
|
Note that no big harm is done if postmaster thinks that a walsender is a
|
|
|
|
regular backend; it will just terminate the walsender earlier in the shutdown
|
2012-08-31 10:30:11 +02:00
|
|
|
phase. A walsender will look like a regular backend until it's done with the
|
2010-01-15 10:19:10 +01:00
|
|
|
initialization and has marked itself in PMSignal array, and at process
|
|
|
|
termination, after unmarking the PMSignal slot.
|
|
|
|
|
2011-03-10 14:59:59 +01:00
|
|
|
Each walsender allocates an entry from the WalSndCtl array, and tracks
|
|
|
|
information about replication progress. User can monitor them via
|
|
|
|
statistics views.
|
2010-01-15 10:19:10 +01:00
|
|
|
|
|
|
|
|
|
|
|
Walsender - walreceiver protocol
|
|
|
|
--------------------------------
|
|
|
|
|
|
|
|
See manual.
|