src/backend/replication/README

   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.