| 1 |
src/backend/replication/README |
| 2 |
|
| 3 |
Walreceiver - libpqwalreceiver API |
| 4 |
---------------------------------- |
| 5 |
|
| 6 |
The transport-specific part of walreceiver, responsible for connecting to |
| 7 |
the primary server, receiving WAL files and sending messages, is loaded |
| 8 |
dynamically to avoid having to link the main server binary with libpq. |
| 9 |
The dynamically loaded module is in libpqwalreceiver subdirectory. |
| 10 |
|
| 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. |
| 13 |
|
| 14 |
This API should be considered internal at the moment, but we could open it |
| 15 |
up for 3rd party replacements of libpqwalreceiver in the future, allowing |
| 16 |
pluggable methods for receiving WAL. |
| 17 |
|
| 18 |
Walreceiver IPC |
| 19 |
--------------- |
| 20 |
|
| 21 |
When the WAL replay in startup process has reached the end of archived WAL, |
| 22 |
restorable using restore_command, it starts up the walreceiver process |
| 23 |
to fetch more WAL (if streaming replication is configured). |
| 24 |
|
| 25 |
Walreceiver is a postmaster subprocess, so the startup process can't fork it |
| 26 |
directly. Instead, it sends a signal to postmaster, asking postmaster to launch |
| 27 |
it. Before that, however, startup process fills in WalRcvData->conninfo |
| 28 |
and WalRcvData->slotname, and initializes the starting point in |
| 29 |
WalRcvData->receiveStart. |
| 30 |
|
| 31 |
As walreceiver receives WAL from the primary server, and writes and flushes |
| 32 |
it to disk (in pg_wal), it updates WalRcvData->flushedUpto and signals |
| 33 |
the startup process to know how far WAL replay can advance. |
| 34 |
|
| 35 |
Walreceiver sends information about replication progress to the primary server |
| 36 |
whenever it either writes or flushes new WAL, or the specified interval elapses. |
| 37 |
This is used for reporting purpose. |
| 38 |
|
| 39 |
Walsender IPC |
| 40 |
------------- |
| 41 |
|
| 42 |
At shutdown, postmaster handles walsender processes differently from regular |
| 43 |
backends. It waits for regular backends to die before writing the |
| 44 |
shutdown checkpoint and terminating pgarch and other auxiliary processes, but |
| 45 |
that's not desirable for walsenders, because we want the standby servers to |
| 46 |
receive all the WAL, including the shutdown checkpoint, before the primary |
| 47 |
is shut down. Therefore postmaster treats walsenders like the pgarch process, |
| 48 |
and instructs them to terminate at the PM_WAIT_XLOG_ARCHIVAL phase, after all |
| 49 |
regular backends have died and checkpointer has issued the shutdown checkpoint. |
| 50 |
|
| 51 |
When postmaster accepts a connection, it immediately forks a new process |
| 52 |
to handle the handshake and authentication, and the process initializes to |
| 53 |
become a backend. Postmaster doesn't know if the process becomes a regular |
| 54 |
backend or a walsender process at that time - that's indicated in the |
| 55 |
connection handshake - so we need some extra signaling to let postmaster |
| 56 |
identify walsender processes. |
| 57 |
|
| 58 |
When walsender process starts up, it marks itself as a walsender process in |
| 59 |
the PMSignal array. That way postmaster can tell it apart from regular |
| 60 |
backends. |
| 61 |
|
| 62 |
Note that no big harm is done if postmaster thinks that a walsender is a |
| 63 |
regular backend; it will just terminate the walsender earlier in the shutdown |
| 64 |
phase. A walsender will look like a regular backend until it's done with the |
| 65 |
initialization and has marked itself in PMSignal array, and at process |
| 66 |
termination, after unmarking the PMSignal slot. |
| 67 |
|
| 68 |
Each walsender allocates an entry from the WalSndCtl array, and tracks |
| 69 |
information about replication progress. User can monitor them via |
| 70 |
statistics views. |
| 71 |
|
| 72 |
|
| 73 |
Walsender - walreceiver protocol |
| 74 |
-------------------------------- |
| 75 |
|
| 76 |
See manual. |