{"canonical_url":"https://engineer.company/glossary/replication/","content_markdown":"# Replication\n\n## What it is\n\nReplication keeps copies of a database on other servers and sends each copy\nevery change made to the original, so that they all stay in step. Where the\ncontext leaves room for doubt it is called database replication. The PostgreSQL\ndocumentation calls the one server that accepts writes the primary and the\nservers that follow it standbys. Redis speaks of a master and its replicas.\n\nPostgreSQL has two kinds, and they copy different things.\n\nPhysical replication copies the write-ahead log (WAL), the record every change\nis written to before it reaches the data files. A standby replays that log and\nbecomes a block-for-block copy of the whole cluster. In streaming replication,\nthe standby keeps a connection open to the primary and receives WAL records as\nthey are generated, instead of waiting for finished WAL files to be shipped. A\nstandby that only replays, and accepts no connections until it is promoted, is a\nwarm standby; one that also answers read-only queries is a hot standby.\n\nLogical replication copies changes to rows. A publisher sends on the inserts,\nupdates and deletes made to chosen tables, each row identified by its replica\nidentity, normally the primary key, and a subscriber applies them to its own\ntables. Because it deals in rows rather than disk blocks, it can carry a few\ntables instead of the whole cluster, even to a different major version of\nPostgreSQL.\n\nStreaming replication is asynchronous by default. The primary confirms a commit\nonce the WAL is on its own disk and sends it on afterwards; the documentation\nputs the delay at typically under one second when the standby can keep up. With\nsynchronous replication switched on, the commit waits until a standby has the\nWAL as well.\n\n## Why it matters\n\nThe first reason is surviving the loss of a server. When the primary fails, a\nstandby that already holds the data can be promoted and take the traffic, far\nsooner than a backup could be restored onto a fresh machine.\n\nThe second is spreading the reads. In many applications most queries only read,\nand a hot standby can answer them, leaving the primary free for the writes,\nwhich only it can take.\n\nThe third is moving data. Logical replication can copy just the tables a\nreporting database needs, or carry data across to a server on another major\nversion of PostgreSQL.\n\nEvery copy comes with a choice between waiting and losing. Asynchronous\nreplication costs nothing on the commit path, but a standby is always slightly\nbehind: a read from it may miss a write that has just happened, and if the\nprimary dies, commits it had already confirmed may never reach the standby that\ntakes over. Synchronous replication closes that gap and puts a network round\ntrip into every commit.\n\nReplication is also not a backup. A standby faithfully replays an accidental\n`DELETE` without a `WHERE`, so within moments every copy has the mistake too.\nUndoing it still takes a backup.\n\n## What it looks like in practice\n\nA shop runs its database on one primary at `10.0.0.1` and adds a second server,\n`db2`, as a streaming replica. On `db2`, with PostgreSQL installed and stopped:\n\n```sh\npg_basebackup -h 10.0.0.1 -U replicator -D /srv/pgdata \\\n    -R -C -S db2_slot -P\n```\n\n`pg_basebackup` copies the whole running cluster into the directory named by\n`-D`, which it creates if needed and which must otherwise be empty, and by\ndefault streams the WAL generated during the copy alongside it. `-C -S db2_slot`\nfirst creates a replication slot on the primary, so that the primary keeps each\nWAL record until the new standby has received it. `-R` creates a\n`standby.signal` file and appends the connection settings, slot included, to\n`postgresql.auto.conf`. `-P` reports progress. The role `replicator` needs the\n`REPLICATION` attribute or superuser rights, and the primary's `pg_hba.conf` has\nto allow the replication connection.\n\nWhen PostgreSQL starts on `db2`, `standby.signal` makes it come up as a standby\nand stream from the primary, and since `hot_standby` is on by default it takes\nread-only queries once it is consistent. On the primary, one row per standby\nshows how it is doing:\n\n```sql\nSELECT application_name, state, sync_state, replay_lsn, replay_lag\nFROM   pg_stat_replication;\n```\n\nA healthy replica shows `state` as `streaming` and `sync_state` as `async`.\n`replay_lag` approximates how long recent commits took to become visible there;\nonce the standby has caught up and WAL activity stops, it goes back to NULL\nrather than showing zero.\n\nThe note on\n[optimising the database before you shard it](/notes/optimise-before-you-shard/)\nexplains why a shop does this. Most of its traffic reads: the product page, the\nbasket, the order history. None of that needs the primary, which has to stay\nfree for writes. A streaming replica takes those reads, and the note points out\nthat adding one is configuration, where a shard is a project. It adds two\ncautions. A replica runs a little behind, so what a user has just written should\nbe read from the primary. And a long report on a replica can be cancelled when\nit holds up the changes the replica is replaying.\n\nMaking a commit wait for a standby takes one setting on the primary. Each\nstandby is named by the `application_name` in its `primary_conninfo`, and the\nprimary lists the names it may wait for:\n\n```ini\nsynchronous_standby_names = 'ANY 1 (db2, db3)'\n```\n\nEach commit now waits until its WAL is on disk on the primary and on at least\none of `db2` and `db3`. `synchronous_commit` can be set per user, per database\nor per transaction, so the order that takes payment can wait while a page-view\ncounter commits at local speed. The note on\n[selling the last ticket exactly once](/notes/selling-limited-stock-without-overselling/)\nshows why that matters for stock. With asynchronous replication, a primary can\nconfirm a sale and die before its replica has it; the replica is promoted, the\nsale is gone, and the same unit is sold again. The note's remedy is a\nsynchronous standby or a store built on Raft, at the price of added latency on\nevery commit.\n\nLogical replication takes two statements. The publisher needs\n`wal_level = logical`, and the tables must already exist on the subscriber,\nbecause their definitions are not copied:\n\n```sql\n-- on the publisher\nCREATE PUBLICATION shop_pub FOR TABLE orders, customers;\n\n-- on the subscriber\nCREATE SUBSCRIPTION shop_sub\n    CONNECTION 'host=10.0.0.1 dbname=shop user=replicator'\n    PUBLICATION shop_pub;\n```\n\nThe subscription first copies the rows already in those tables, then applies\nevery change made after that.\n\n## Where it goes wrong\n\n**A user cannot see what they just wrote.** The application writes to the\nprimary and reads back from a replica that is still a moment behind, so a saved\nsetting seems to revert. Route a user's reads to the primary for a short time\nafter they write. Where data must be visible on the standby the moment the\ncommit returns, `synchronous_commit = remote_apply` waits until the synchronous\nstandbys have replayed the transaction, at a higher cost per commit.\n\n**Long queries on the replica are cancelled.** The standby has to replay changes\nthat clash with a running query: vacuum removing row versions the query can\nstill see, or the exclusive lock taken by `DROP TABLE` and many forms of\n`ALTER TABLE`. Replay waits up to `max_standby_streaming_delay`, 30 seconds by\ndefault, then cancels the query. A reporting replica can be given a longer\ndelay, and falls further behind while it waits. `hot_standby_feedback = on`\nstops the cancellations caused by vacuum, but the documentation warns it can\nbloat the primary. `pg_stat_database_conflicts` on the standby counts the\ncancellations by cause, and the application should retry a cancelled query.\n\n**A forgotten slot fills the primary's disk.** A slot holds WAL until its\nstandby has received it, even when that standby is switched off or long gone,\nand `max_slot_wal_keep_size` is -1 by default, meaning no limit. Check the slots\nregularly:\n\n```sql\nSELECT slot_name, active, wal_status, safe_wal_size\nFROM   pg_replication_slots;\n```\n\nDrop a slot whose standby is gone. Setting `max_slot_wal_keep_size` caps what a\nslot may hold; a standby that falls further behind finds its slot invalidated,\nwith `wal_status` showing `lost`. `idle_replication_slot_timeout`, off by\ndefault, invalidates slots left inactive for longer than the time given.\n\n**Writes stop when a synchronous standby does.** With one standby named and that\nstandby down, every commit on the primary waits, and may never complete. Name\nmore candidates than the number required, as in `ANY 1 (db2, db3)`. Failing\nthat, lower the number or empty `synchronous_standby_names` and reload the\nconfiguration.\n\n**Two servers both believe they are the primary.** PostgreSQL promotes a standby\nwhen asked, with `pg_ctl promote` or `SELECT pg_promote()`, but has no software\nof its own to detect a failed primary, and nothing stops the old one coming back\nand taking writes. The documentation warns this leads to \"confusion and\nultimately data loss\". Fence the old primary off, by powering it down or cutting\nits network, before promoting, and rebuild it as a standby before it rejoins.\n\n**Logical replication leaves things behind.** Schema changes are not replicated,\nso a column added on the publisher stops replication until the subscriber has it\ntoo; apply additive changes to the subscriber first. Sequences are not\nreplicated either: rows arrive with their IDs, but the subscriber's sequences\nstill stand at their start values, and inserts after a switchover fail on\nduplicate keys. Before switching, set each sequence past the highest value in\nuse.\n\n**A Redis master restarts empty and takes its replicas with it.** If persistence\nis off on the master and something restarts it automatically, it comes back with\nan empty dataset and its replicas copy that, deleting their own data. Keep\npersistence on, or do not let the master restart automatically.\n\n## Further reading\n\n- [High availability](https://www.postgresql.org/docs/current/high-availability.html)\n  — the PostgreSQL overview of primary and standby servers, synchronous and\n  asynchronous replication, and failover.\n- [Log-Shipping Standby Servers](https://www.postgresql.org/docs/current/warm-standby.html)\n  — streaming replication, replication slots and how to configure synchronous\n  replication.\n- [Hot Standby](https://www.postgresql.org/docs/current/hot-standby.html) —\n  read-only queries on a standby, the conflicts that cancel them, and the\n  settings that trade lag against cancellations.\n- [pg_basebackup](https://www.postgresql.org/docs/current/app-pgbasebackup.html)\n  — copying a running cluster to start a standby, with every option used above.\n- [Restrictions](https://www.postgresql.org/docs/current/logical-replication-restrictions.html)\n  — what logical replication does not carry: schema, sequences, large objects\n  and anything other than tables.\n- [Redis replication](https://redis.io/docs/latest/operate/oss_and_stack/management/replication/)\n  — how Redis replicas follow a master, why replication is asynchronous, and the\n  danger of restarting without persistence.\n\n\u003chttps://engineer.company/glossary/replication/\u003e\n","date_modified":"2026-10-29T11:17:41Z","description":"How database replication keeps standby servers in step: streaming and logical replication in PostgreSQL, synchronous or not, and the failures to plan for.","formats":{"gemtext":"https://engineer.company/glossary/replication/index.gmi","gopher":"https://engineer.company/glossary/replication/gophermap","html":"https://engineer.company/glossary/replication/","json":"https://engineer.company/glossary/replication/index.json","markdown":"https://engineer.company/glossary/replication/index.md","pdf":"https://engineer.company/glossary/replication/index.pdf"},"kind":"page","language":"en","title":"What is replication?","url":"https://engineer.company/glossary/replication/","version":1}