replication-overview

# Replication — operational orientation

For the conceptual model (slot lifetimes, decoding pipeline, conflict semantics)
read `knowledge/architecture/replication.md`.

## Which kind of replication?

| If the user wants… | Flavor | Key GUCs |
|---|---|---|
| Hot standby, byte-identical copy, optional read queries | **Physical streaming** | `wal_level=replica`, `max_wal_senders`, `primary_conninfo`, `primary_slot_name` |
| Point-in-time recovery from a base backup + WAL archive | **Physical archive (PITR)** | `wal_level=replica`, `archive_mode`, `archive_command`/`archive_library`, `restore_command` |
| Stream row-level changes to a non-PG consumer (CDC, audit, custom sink) | **Logical decoding** via SQL or replication-protocol API + an output plugin | `wal_level=logical`, `max_replication_slots`, plugin (e.g. `test_decoding`, `pgoutput`) |
| Selective table replication between PG clusters, schema-agnostic upgrade, cross-version | **Logical replication** (`CREATE PUBLICATION` / `CREATE SUBSCRIPTION`) | `wal_level=logical`, `max_replication_slots`, `max_logical_replication_workers`, `max_sync_workers_per_subscription`, `max_parallel_apply_workers_per_subscription` |
| Wait-for-ACK durability on commit | **Synchronous replication** (overlay on physical or logical) | `synchronous_standby_names`, `synchronous_commit` |
| Standbys keep logical slots in sync for failover | **Slot sync** | `sync_replication_slots`, `synchronized_standby_slots`, slot `failover=true` |

[from-comment `source/src/backend/replication/walsender.c:5-18`;
from-comment `source/src/backend/replication/walreceiver.c:5-17`;
from-comment `source/src/backend/replication/syncrep.c:5-58`;
from-comment `source/src/backend/replication/logical/launcher.c:10-15,53-56`]

## wal_level — what it gates

- `minimal` — only crash recovery; no walsenders, no archive, no replication of
  any kind.
- `replica` — adds enough info for physical streaming and PITR archive.
- `logical` — additionally logs the data needed by `reorderbuffer` to reconstruct
  row changes (replica identity, etc.). Required for logical decoding and
  logical replication.

[from-code `source/src/backend/utils/misc/guc_tables.c:525,649` — `wal_level_options`, `effective_wal_level`]

## Where to look in source

### Physical streaming
- Sender: `source/src/backend/replication/walsender.c` (~134 KB). Handles
  replication-protocol commands `IDENTIFY_SYSTEM`, `BASE_BACKUP`,
  `CREATE_REPLICATION_SLOT`, `START_REPLICATION`. Grammar:
  `source/src/backend/replication/repl_gram.y:62-300`.
  Batch size: `MAX_SEND_SIZE = XLOG_BLCKSZ * 16` (~128 KB with default 8K
  blocks) — `walsender.c:110-118`.
- Receiver: `source/src/backend/replication/walreceiver.c` + the dynamically
  loaded `libpqwalreceiver/` (keeps libpq out of the main server binary).
  [from-README `source/src/backend/replication/README:3-16`]
- Postmaster signaling for walsender lifecycle:
  `source/src/backend/replication/README:39-70`.

### Replication slots (physical and logical)
- `source/src/backend/replication/slot.c` — allocation, on-disk format,
  invalidation causes (`RS_INVAL_WAL_REMOVED`, `RS_INVAL_HORIZON`,
  `RS_INVAL_WAL_LEVEL`, `RS_INVAL_IDLE_TIMEOUT`).
  [from-code `source/src/include/replication/slot.h:58-72`]
- SQL surface: `slotfuncs.c`.
- Persistency states `RS_PERSISTENT | RS_EPHEMERAL | RS_TEMPORARY` —
  `source/src/include/replication/slot.h:43-48`.
- On-disk fields the user actually monitors: `restart_lsn`, `catalog_xmin`,
  `confirmed_flush`, `invalidated`, `two_phase`, `failover`, `synced`
  (`slot.h:95-162`).

### Logical decoding pipeline
- Coordinator: `source/src/backend/replication/logical/logical.c` — sets up
  `LogicalDecodingContext`, wraps output-plugin callbacks
  (`source/src/backend/replication/logical/logical.c:57-80`).
- Decoder: `source/src/backend/replication/logical/decode.c` — turns xlog
  records into `reorderbuffer` calls.
- Reassembly + spill-to-disk: `source/src/backend/replication/logical/reorderbuffer.c`
  (≈162 KB; ships in-progress transactions to disk under memory pressure —
  `reorderbuffer.c:33-83`).
- Catalog snapshots for decoding: `logical/snapbuild.c`.
- Output plugins: contract in `source/src/include/replication/output_plugin.h:36,216-243`
  (`_PG_output_plugin_init`, `OutputPluginCallbacks`). Built-in plugin used by
  logical replication: `source/src/backend/replication/pgoutput/`.

### Logical replication (PUB/SUB)
- Launcher (bgworker spawning per-subscription): `logical/launcher.c`.
- Apply worker: `logical/worker.c` (~194 KB). Streaming and two-phase notes at
  `worker.c:22-80`.
- Initial table sync: `logical/tablesync.c` — state machine
  `INIT → DATASYNC → FINISHEDCOPY → SYNCWAIT → CATCHUP → SYNCDONE → READY`
  (`tablesync.c:29-55`).
- Parallel apply: `logical/applyparallelworker.c`.
- Conflict logging (v18): `logical/conflict.c` — types in
  `ConflictTypeNames[]` (`conflict.c:27-36`).
- Sequence sync: `logical/sequencesync.c`.
- Slot sync to standby: `logical/slotsync.c`. The three sync-ready
  preconditions (standby WAL past remote `confirmed_flush_lsn`; catalog xmin
  not behind; consistent snapshot buildable at `restart_lsn` before
  `confirmed_flush_lsn`) — `slotsync.c:11-40`. Mirror slots stay
  `RS_TEMPORARY` until all three hold, then flip to `RS_PERSISTENT` with
  `synced=true`. Full discussion in `knowledge/architecture/replication.md` §2.
- Replication origins: `logical/origin.c`.

### Synchronous replication
- `source/src/backend/replication/syncrep.c` — wait queue on the primary; FIRST
  (priority) vs ANY (quorum) parsed by `syncrep_gram.y`
  (`syncrep.c:32-58`).

## Knob cheatsheet

```
# Primary (any flavor)
wal_level = replica | logical
max_wal_senders = 10
max_replication_slots = 10

# Standby (physical)
primary_conninfo = 'host=... user=replication'
primary_slot_name = 'standby_1'        # ties to a physical slot
hot_standby = on

# Logical replication subscriber
max_logical_replication_workers = 4    # launcher.c:54
max_sync_workers_per_subscription = 2  # launcher.c:55
max_parallel_apply_workers_per_subscription = 2  # launcher.c:56

# Logical decoding tuning
logical_decoding_work_mem = 64MB       # per-reorderbuffer memory ceiling
                                       # before the LARGEST in-progress txn
                                       # spills to disk (reorderbuffer.c)

# Synchronous
synchronous_standby_names = 'FIRST 2 (s1, s2, s3)'   # or 'ANY 2 (...)'
synchronous_commit = on | remote_apply | remote_write | local | off

# Failover slots (v17+)
sync_replication_slots = on            # on standby
synchronized_standby_slots = 's1,s2'   # on primary
```

## Common diagnostic views

- `pg_stat_replication` — one row per active walsender (on primary).
- `pg_stat_wal_receiver` — on standby.
- `pg_replication_slots` — slot state, `restart_lsn`, `confirmed_flush_lsn`,
  `wal_status`, `invalidation_reason`.
- `pg_stat_subscription`, `pg_stat_subscription_stats` — subscriber side.
- `pg_replication_origin_status` — apply progress per origin.

## Replication-protocol commands (psql `replication=true`)

`IDENTIFY_SYSTEM`, `CREATE_REPLICATION_SLOT slot {PHYSICAL|LOGICAL plugin} ...`,
`START_REPLICATION [SLOT s] {PHYSICAL %X/%X [TIMELINE n] | SLOT s LOGICAL %X/%X options}`,
`BASE_BACKUP (...)`, `READ_REPLICATION_SLOT`, `DROP_REPLICATION_SLOT`,
`TIMELINE_HISTORY`.
[from-code `source/src/backend/replication/repl_gram.y:62-300`]

## When to send the user deeper

- "Why is my slot blocking WAL recycling?" → slot's `restart_lsn` /
  `catalog_xmin`; see `knowledge/architecture/replication.md` §slots.
- "How do I write an output plugin?" → `output_plugin.h` callbacks +
  `contrib/test_decoding` as canonical example. Docs:
  https://www.postgresql.org/docs/current/logicaldecoding.html.
- "Subscriber missed an UPDATE" → conflict types in `logical/conflict.c`; in
  v18 logging is automatic.
- "Failover broke my logical subscription" → slot sync chapter + `failover`
  flag on slot.
- "Why is my logical slot stuck behind a physical standby?" →
  `synchronized_standby_slots` gate + the walsender wakeup chain
  (`WalSndWaitForWal` → `PhysicalWakeupLogicalWalSnd` →
  `wal_confirm_rcv_cv`). See `knowledge/architecture/replication.md` §2.

## Files examined for this skill

| file | lines | depth |
|---|---|---|
| `source/src/backend/replication/README` | 1-76 | full |
| `source/src/backend/replication/walsender.c` | 1-120 | header |
| `source/src/backend/replication/walreceiver.c` | 1-80 | header |
| `source/src/backend/replication/slot.c` | 1-100 | header |
| `source/src/include/replication/slot.h` | 1-200 | partial |
| `source/src/backend/replication/syncrep.c` | 1-80 | header |
| `source/src/backend/replication/logical/decode.c` | 1-80 | header |
| `source/src/backend/replication/logical/reorderbuffer.c` | 1-120 | header |
| `source/src/backend/replication/logical/logical.c` | 1-80 | header |
| `source/src/backend/replication/logical/worker.c` | 1-80 | header |
| `source/src/backend/replication/logical/tablesync.c` | 1-80 | header |
| `source/src/backend/replication/logical/launcher.c` | 1-60 | header |
| `source/src/backend/replication/logical/conflict.c` | 1-60 | header |
| `source/src/backend/replication/repl_gram.y` | grep | command surface |
| `source/src/include/replication/output_plugin.h` | grep | callback contract |

## Cross-references

- `.claude/skills/wal-and-xlog/SKILL.md` — WAL records consumed by walsenders; `rm_decode` for logical decoding visibility.
- `.claude/skills/locking/SKILL.md` — `ProcArrayLock`, `ReplicationSlotControlLock`, `SyncRepLock` ordering; standby-conflict-detection.
- `.claude/skills/bgworker-and-extensions/SKILL.md` — logical-replication apply workers are bgworkers; subscription launcher manages them.
- `.claude/skills/error-handling/SKILL.md` — apply-worker error escalation; conflict detection in logical replication.
- `.claude/skills/testing/SKILL.md` — TAP tests in `src/test/recovery/t/`, `src/test/subscription/t/`.
- `knowledge/architecture/replication.md` — long-form architecture.
- `knowledge/subsystems/replication.md` — deep-dive corpus doc covering both physical and logical replication.