mirror of
https://github.com/postgres/postgres.git
synced 2025-11-15 00:04:08 -05:00
641dd167a3
src/backend/replication/README includes since 32bc08b a basic description of the WAL receiver hooks available in walreceiver.h for a module like libpqwalreceiver, but the README has never been updated to reflect changes done to the hooks, so the contents of the README have rotten with the time. This commit moves the description from the README to walreceiver.h, where it will be hard to miss that a description update or addition is needed depending on the modifications done to the hooks. 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 Paquier Reviewed-by: Peter Eisentraut Discussion: https://postgr.es/m/20200502024606.GA471944@paquier.xyz
77 lines
3.4 KiB
Plaintext
77 lines
3.4 KiB
Plaintext
src/backend/replication/README
|
|
|
|
Walreceiver - libpqwalreceiver API
|
|
----------------------------------
|
|
|
|
The transport-specific part of walreceiver, responsible for connecting to
|
|
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.
|
|
|
|
The dynamically loaded module implements a set of functions with details
|
|
about each one of them provided in src/include/replication/walreceiver.h.
|
|
|
|
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
|
|
pluggable methods for receiving WAL.
|
|
|
|
Walreceiver IPC
|
|
---------------
|
|
|
|
When the WAL replay in startup process has reached the end of archived WAL,
|
|
restorable using restore_command, it starts up the walreceiver process
|
|
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
|
|
it. Before that, however, startup process fills in WalRcvData->conninfo
|
|
and WalRcvData->slotname, and initializes the starting point in
|
|
WalRcvData->receiveStart.
|
|
|
|
As walreceiver receives WAL from the master server, and writes and flushes
|
|
it to disk (in pg_wal), it updates WalRcvData->flushedUpto and signals
|
|
the startup process to know how far WAL replay can advance.
|
|
|
|
Walreceiver sends information about replication progress to the master server
|
|
whenever it either writes or flushes new WAL, or the specified interval elapses.
|
|
This is used for reporting purpose.
|
|
|
|
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
|
|
backends have died and checkpointer has issued the shutdown checkpoint.
|
|
|
|
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
|
|
phase. A walsender will look like a regular backend until it's done with the
|
|
initialization and has marked itself in PMSignal array, and at process
|
|
termination, after unmarking the PMSignal slot.
|
|
|
|
Each walsender allocates an entry from the WalSndCtl array, and tracks
|
|
information about replication progress. User can monitor them via
|
|
statistics views.
|
|
|
|
|
|
Walsender - walreceiver protocol
|
|
--------------------------------
|
|
|
|
See manual.
|