{
  "schema_version": 2,
  "id": "operate/oss_and_stack/management/replication",
  "title": "Redis replication",
  "url": "https://redis.io/docs/latest/operate/oss_and_stack/management/replication/",
  "summary": "How Redis supports high availability and failover with replication",
  "aliases": [
    "/manual/replication/",
    "/management/replication/",
    "/operate/replication/"
  ],
  "tags": [
    "docs",
    "operate",
    "stack",
    "oss"
  ],
  "last_updated": "2026-09-21T15:59:03+01:00",
  "page_type": "content",
  "content_hash": "cd4755cd72311f09647f1ced97d1437f5b5561c241cd93d2575203480f8a8b7e",
  "sections": [
    {
      "id": "overview",
      "title": "Overview",
      "role": "overview",
      "text": "At the base of Redis replication (excluding the high availability features provided as an additional layer by Redis Cluster or Redis Sentinel) there is a *leader follower* (master-replica) replication that is simple to use and configure. It allows replica Redis instances to be exact copies of master instances. The replica will automatically reconnect to the master every time the link breaks, and will attempt to be an exact copy of it *regardless* of what happens to the master.\n\nThis system works using three main mechanisms:\n\n1. When a master and a replica instance are well-connected, the master keeps the replica updated by sending a stream of commands to the replica to replicate the effects on the dataset happening on the master side due to: client writes, keys expired or evicted, any other action changing the master dataset.\n2. When the link between the master and the replica breaks, for network issues or because a timeout is sensed in the master or the replica, the replica reconnects and attempts to proceed with a partial resynchronization: it means that it will try to just obtain the part of the stream of commands it missed during the disconnection.\n3. When a partial resynchronization is not possible, the replica will ask for a full resynchronization. This will involve a more complex process in which the master needs to create a snapshot of all its data, send it to the replica, and then continue sending the stream of commands as the dataset changes.\n\nRedis uses by default asynchronous replication, which being low latency and\nhigh performance, is the natural replication mode for the vast majority of Redis\nuse cases. However, Redis replicas asynchronously acknowledge the amount of data\nthey receive periodically with the master. So the master does not wait every time\nfor a command to be processed by the replicas, however it knows, if needed, what\nreplica already processed what command. This allows having optional synchronous replication.\n\nSynchronous replication of certain data can be requested by the clients using\nthe [`WAIT`](https://redis.io/docs/latest/commands/wait) command. However [`WAIT`](https://redis.io/docs/latest/commands/wait) is only able to ensure there are the\nspecified number of acknowledged copies in the other Redis instances, it does not\nturn a set of Redis instances into a CP system with strong consistency: acknowledged\nwrites can still be lost during a failover, depending on the exact configuration\nof the Redis persistence. However, [WAIT](https://redis.io/docs/latest/commands/wait) dramatically reduces the probability of losing a write after a failure event to specific hard-to-trigger failure modes.\n\nYou can check the Redis Sentinel or Redis Cluster documentation for more information\nabout high availability and failover. The rest of this document mainly describes the basic characteristics of Redis basic replication."
    },
    {
      "id": "important-facts-about-redis-replication",
      "title": "Important facts about Redis replication",
      "role": "content",
      "text": "* Redis uses asynchronous replication, with asynchronous replica-to-master acknowledges of the amount of data processed.\n* A master can have multiple replicas.\n* Replicas are able to accept connections from other replicas. Aside from connecting a number of replicas to the same master, replicas can also be connected to other replicas in a cascading-like structure. Since Redis 4.0, all the sub-replicas will receive exactly the same replication stream from the master.\n* Redis replication is non-blocking on the master side. This means that the master will continue to handle queries when one or more replicas perform the initial synchronization or a partial resynchronization.\n* Replication is also largely non-blocking on the replica side. While the replica is performing the initial synchronization, it can handle queries using the old version of the dataset, assuming you configured Redis to do so in redis.conf.  Otherwise, you can configure Redis replicas to return an error to clients if the replication stream is down. However, after the initial sync, the old dataset must be deleted and the new one must be loaded. The replica will block incoming connections during this brief window (that can be as long as many seconds for very large datasets). Since Redis 4.0 you can configure Redis so that the deletion of the old data set happens in a different thread, however loading the new initial dataset will still happen in the main thread and block the replica.\n* Replication can be used both for scalability, to have multiple replicas for read-only queries (for example, slow O(N) operations can be offloaded to replicas), or simply for improving data safety and high availability.\n* You can use replication to avoid the cost of having the master writing the full dataset to disk: a typical technique involves configuring your master `redis.conf` to avoid persisting to disk at all, then connect a replica configured to save from time to time, or with AOF enabled. However, this setup must be handled with care, since a restarting master will start with an empty dataset: if the replica tries to sync with it, the replica will be emptied as well."
    },
    {
      "id": "safety-of-replication-when-master-has-persistence-turned-off",
      "title": "Safety of replication when master has persistence turned off",
      "role": "content",
      "text": "In setups where Redis replication is used, it is strongly advised to have\npersistence turned on in the master and in the replicas. When this is not possible,\nfor example because of latency concerns due to very slow disks, instances should\nbe configured to **avoid restarting automatically** after a reboot.\n\nTo better understand why masters with persistence turned off configured to\nauto restart are dangerous, check the following failure mode where data\nis wiped from the master and all its replicas:\n\n1. We have a setup with node A acting as master, with persistence turned down, and nodes B and C replicating from node A.\n2. Node A crashes, however it has some auto-restart system, that restarts the process. However since persistence is turned off, the node restarts with an empty data set.\n3. Nodes B and C will replicate from node A, which is empty, so they'll effectively destroy their copy of the data.\n\nWhen Redis Sentinel is used for high availability, also turning off persistence\non the master, together with auto restart of the process, is dangerous. For example the master can restart fast enough for Sentinel to not detect a failure, so that the failure mode described above happens.\n\nEvery time data safety is important, and replication is used with master configured without persistence, auto restart of instances should be disabled."
    },
    {
      "id": "how-redis-replication-works",
      "title": "How Redis replication works",
      "role": "content",
      "text": "Every Redis master has a replication ID: it is a large pseudo random string\nthat marks a given history of the dataset. Each master also takes an offset that\nincrements for every byte of replication stream that it is produced to be\nsent to replicas, to update the state of the replicas with the new changes\nmodifying the dataset. The replication offset is incremented even if no replica\nis actually connected, so basically every given pair of:\n\n    Replication ID, offset\n\nIdentifies an exact version of the dataset of a master.\n\nWhen replicas connect to masters, they use the [`PSYNC`](https://redis.io/docs/latest/commands/psync) command to send\ntheir old master replication ID and the offsets they processed so far. This way\nthe master can send just the incremental part needed. However if there is not\nenough *backlog* in the master buffers, or if the replica is referring to an\nhistory (replication ID) which is no longer known, then a full resynchronization\nhappens: in this case the replica will get a full copy of the dataset, from scratch.\n\nThis is how a full synchronization works in more details:\n\nThe master starts a background saving process to produce an RDB file. At the same time it starts to buffer all new write commands received from the clients. When the background saving is complete, the master transfers the database file to the replica, which saves it on disk, and then loads it into memory. The master will then send all buffered commands to the replica. This is done as a stream of commands and is in the same format of the Redis protocol itself.\n\nYou can try it yourself via telnet. Connect to the Redis port while the\nserver is doing some work and issue the [`SYNC`](https://redis.io/docs/latest/commands/sync) command. You'll see a bulk\ntransfer and then every command received by the master will be re-issued\nin the telnet session. Actually [`SYNC`](https://redis.io/docs/latest/commands/sync) is an old protocol no longer used by\nnewer Redis instances, but is still there for backward compatibility: it does\nnot allow partial resynchronizations, so now [`PSYNC`](https://redis.io/docs/latest/commands/psync) is used instead.\n\nAs already said, replicas are able to automatically reconnect when the master-replica link goes down for some reason. If the master receives multiple concurrent replica synchronization requests, it performs a single background save in to serve all of them."
    },
    {
      "id": "replication-id-explained",
      "title": "Replication ID explained",
      "role": "content",
      "text": "In the previous section we said that if two instances have the same replication\nID and replication offset, they have exactly the same data. However it is useful\nto understand what exactly is the replication ID, and why instances have actually\ntwo replication IDs: the main ID and the secondary ID.\n\nA replication ID basically marks a given *history* of the data set. Every time\nan instance restarts from scratch as a master, or a replica is promoted to master,\na new replication ID is generated for this instance. The replicas connected to\na master will inherit its replication ID after the handshake. So two instances\nwith the same ID are related by the fact that they hold the same data, but\npotentially at a different time. It is the offset that works as a logical time\nto understand, for a given history (replication ID), who holds the most updated\ndata set.\n\nFor instance, if two instances A and B have the same replication ID, but one\nwith offset 1000 and one with offset 1023, it means that the first lacks certain\ncommands applied to the data set. It also means that A, by applying just a few\ncommands, may reach exactly the same state of B.\n\nThe reason why Redis instances have two replication IDs is because of replicas\nthat are promoted to masters. After a failover, the promoted replica requires\nto still remember what was its past replication ID, because such replication ID\nwas the one of the former master. In this way, when other replicas will sync\nwith the new master, they will try to perform a partial resynchronization using the\nold master replication ID. This will work as expected, because when the replica\nis promoted to master it sets its secondary ID to its main ID, remembering what\nwas the offset when this ID switch happened. Later it will select a new random\nreplication ID, because a new history begins. When handling the new replicas\nconnecting, the master will match their IDs and offsets both with the current\nID and the secondary ID (up to a given offset, for safety). In short this means\nthat after a failover, replicas connecting to the newly promoted master don't have\nto perform a full sync.\n\nIn case you wonder why a replica promoted to master needs to change its\nreplication ID after a failover: it is possible that the old master is still\nworking as a master because of some network partition: retaining the same\nreplication ID would violate the fact that the same ID and same offset of any\ntwo random instances mean they have the same data set."
    },
    {
      "id": "diskless-replication",
      "title": "Diskless replication",
      "role": "content",
      "text": "Normally a full resynchronization requires creating an RDB file on disk,\nthen reloading the same RDB from disk to feed the replicas with the data.\n\nWith slow disks this can be a very stressing operation for the master.\nRedis version 2.8.18 is the first version to have support for diskless\nreplication. In this setup the child process directly sends the\nRDB over the wire to replicas, without using the disk as intermediate storage."
    },
    {
      "id": "configuration",
      "title": "Configuration",
      "role": "configuration",
      "text": "To configure basic Redis replication is trivial: just add the following line to the replica configuration file:\n\n    replicaof 192.168.1.1 6379\n\nOf course you need to replace 192.168.1.1 6379 with your master IP address (or\nhostname) and port. Alternatively, you can call the [`REPLICAOF`](https://redis.io/docs/latest/commands/replicaof) command and the\nmaster host will start a sync with the replica.\n\nThere are also a few parameters for tuning the replication backlog taken\nin memory by the master to perform the partial resynchronization. See the example\n`redis.conf` shipped with the Redis distribution for more information.\n\nDiskless replication can be enabled using the `repl-diskless-sync` configuration\nparameter. The delay to start the transfer to wait for more replicas to\narrive after the first one is controlled by the `repl-diskless-sync-delay`\nparameter. Please refer to the example `redis.conf` file in the Redis distribution\nfor more details."
    },
    {
      "id": "read-only-replica",
      "title": "Read-only replica",
      "role": "content",
      "text": "Since Redis 2.6, replicas support a read-only mode that is enabled by default.\nThis behavior is controlled by the `replica-read-only` option in the redis.conf file, and can be enabled and disabled at runtime using [`CONFIG SET`](https://redis.io/docs/latest/commands/config-set).\n\nRead-only replicas will reject all write commands, so that it is not possible to write to a replica because of a mistake. This does not mean that the feature is intended to expose a replica instance to the internet or more generally to a network where untrusted clients exist, because administrative commands like [`DEBUG`](https://redis.io/docs/latest/commands/debug) or [`CONFIG`](https://redis.io/docs/latest/commands/config) are still enabled. The [Security](https://redis.io/docs/latest/operate/oss_and_stack/management/security) page describes how to secure a Redis instance.\n\nYou may wonder why it is possible to revert the read-only setting\nand have replica instances that can be targeted by write operations.\nThe answer is that writable replicas exist only for historical reasons.\nUsing writable replicas can result in inconsistency between the master and the replica, so it is not recommended to use writable replicas.\nTo understand in which situations this can be a problem, we need to understand how replication works.\nChanges on the master is replicated by propagating regular Redis commands to the replica.\nWhen a key expires on the master, this is propagated as a DEL command.\nIf a key which exists on the master but is deleted, expired or has a different type on the replica compared to the master will react differently to commands like DEL, INCR or RPOP propagated from the master than intended.\nThe propagated command may fail on the replica or result in a different outcome.\nTo minimize the risks (if you insist on using writable replicas) we suggest you follow these recommendations:\n\n* Don't write to keys in a writable replica that are also used on the master.\n  (This can be hard to guarantee if you don't have control over all the clients that write to the master.)\n\n* Don't configure an instance as a writable replica as an intermediary step when upgrading a set of instances in a running system.\n  In general, don't configure an instance as a writable replica if it can ever be promoted to a master if you want to guarantee data consistency.\n\nHistorically, there were some use cases that were considered legitimate for writable replicas.\nAs of version 7.0, these use cases are now all obsolete and the same can be achieved by other means.\nFor example:\n\n* Computing slow Set or Sorted set operations and storing the result in temporary local keys using commands like [`SUNIONSTORE`](https://redis.io/docs/latest/commands/sunionstore) and [`ZINTERSTORE`](https://redis.io/docs/latest/commands/zinterstore).\n  Instead, use commands that return the result without storing it, such as [`SUNION`](https://redis.io/docs/latest/commands/sunion) and [`ZINTER`](https://redis.io/docs/latest/commands/zinter).\n\n* Using the [`SORT`](https://redis.io/docs/latest/commands/sort) command (which is not considered a read-only command because of the optional STORE option and therefore cannot be used on a read-only replica).\n  Instead, use [`SORT_RO`](https://redis.io/docs/latest/commands/sort_ro), which is a read-only command.\n\n* Using [`EVAL`](https://redis.io/docs/latest/commands/eval) and [`EVALSHA`](https://redis.io/docs/latest/commands/evalsha) are also not considered read-only commands, because the Lua script may call write commands.\n  Instead, use [`EVAL_RO`](https://redis.io/docs/latest/commands/eval_ro) and [`EVALSHA_RO`](https://redis.io/docs/latest/commands/evalsha_ro) where the Lua script can only call read-only commands.\n\nWhile writes to a replica will be discarded if the replica and the master resync or if the replica is restarted, there is no guarantee that they will sync automatically.\n\nBefore version 4.0, writable replicas were incapable of expiring keys with a time to live set.\nThis means that if you use [`EXPIRE`](https://redis.io/docs/latest/commands/expire) or other commands that set a maximum TTL for a key, the key will leak, and while you may no longer see it while accessing it with read commands, you will see it in the count of keys and it will still use memory.\nRedis 4.0 RC3 and greater versions are able to evict keys with TTL as masters do, with the exceptions of keys written in DB numbers greater than 63 (but by default Redis instances only have 16 databases).\nNote though that even in versions greater than 4.0, using [`EXPIRE`](https://redis.io/docs/latest/commands/expire) on a key that could ever exists on the master can cause inconsistency between the replica and the master.\n\nAlso note that since Redis 4.0 replica writes are only local, and are not propagated to sub-replicas attached to the instance. Sub-replicas instead will always receive the replication stream identical to the one sent by the top-level master to the intermediate replicas. So for example in the following setup:\n\n    A ---> B ---> C\n\nEven if `B` is writable, C will not see `B` writes and will instead have identical dataset as the master instance `A`."
    },
    {
      "id": "setting-a-replica-to-authenticate-to-a-master",
      "title": "Setting a replica to authenticate to a master",
      "role": "configuration",
      "text": "If your master has a password via `requirepass`, it's trivial to configure the\nreplica to use that password in all sync operations.\n\nTo do it on a running instance, use `redis-cli` and type:\n\n    config set masterauth <password>\n\nTo set it permanently, add this to your config file:\n\n    masterauth <password>"
    },
    {
      "id": "allow-writes-only-with-n-attached-replicas",
      "title": "Allow writes only with N attached replicas",
      "role": "content",
      "text": "Starting with Redis 2.8, you can configure a Redis master to\naccept write queries only if at least N replicas are currently connected to the\nmaster.\n\nHowever, because Redis uses asynchronous replication it is not possible to ensure\nthe replica actually received a given write, so there is always a window for data\nloss.\n\nThis is how the feature works:\n\n* Redis replicas ping the master every second, acknowledging the amount of replication stream processed.\n* Redis masters will remember the last time it received a ping from every replica.\n* The user can configure a minimum number of replicas that have a lag not greater than a maximum number of seconds.\n\nIf there are at least N replicas, with a lag less than M seconds, then the write will be accepted.\n\nYou may think of it as a best effort data safety mechanism, where consistency is not ensured for a given write, but at least the time window for data loss is restricted to a given number of seconds. In general bound data loss is better than unbound one.\n\nIf the conditions are not met, the master will instead reply with an error and the write will not be accepted.\n\nThere are two configuration parameters for this feature:\n\n* min-replicas-to-write `<number of replicas>`\n* min-replicas-max-lag `<number of seconds>`\n\nFor more information, please check the example `redis.conf` file shipped with the\nRedis source distribution."
    },
    {
      "id": "how-redis-replication-deals-with-expires-on-keys",
      "title": "How Redis replication deals with expires on keys",
      "role": "content",
      "text": "Redis expires allow keys to have a limited time to live (TTL). Such a feature depends\non the ability of an instance to count the time, however Redis replicas correctly\nreplicate keys with expires, even when such keys are altered using Lua\nscripts.\n\nTo implement such a feature Redis cannot rely on the ability of the master and\nreplica to have synced clocks, since this is a problem that cannot be solved\nand would result in race conditions and diverging data sets, so Redis\nuses three main techniques to make the replication of expired keys\nable to work:\n\n1. Replicas don't expire keys, instead they wait for masters to expire the keys. When a master expires a key (or evict it because of LRU), it synthesizes a [`DEL`](https://redis.io/docs/latest/commands/del) command which is transmitted to all the replicas.\n2. However because of master-driven expire, sometimes replicas may still have in memory keys that are already logically expired, since the master was not able to provide the [`DEL`](https://redis.io/docs/latest/commands/del) command in time. To deal with that the replica uses its logical clock to report that a key does not exist **only for read operations** that don't violate the consistency of the data set (as new commands from the master will arrive). In this way replicas avoid reporting logically expired keys that are still existing. In practical terms, an HTML fragments cache that uses replicas to scale will avoid returning items that are already older than the desired time to live.\n3. During Lua scripts executions no key expiries are performed. As a Lua script runs, conceptually the time in the master is frozen, so that a given key will either exist or not for all the time the script runs. This prevents keys expiring in the middle of a script, and is needed to send the same script to the replica in a way that is guaranteed to have the same effects in the data set.\n\nOnce a replica is promoted to a master it will start to expire keys independently, and will not require any help from its old master."
    },
    {
      "id": "configuring-replication-in-docker-and-nat",
      "title": "Configuring replication in Docker and NAT",
      "role": "configuration",
      "text": "When Docker, or other types of containers using port forwarding, or Network Address Translation is used, Redis replication needs some extra care, especially when using Redis Sentinel or other systems where the master [`INFO`](https://redis.io/docs/latest/commands/info) or [`ROLE`](https://redis.io/docs/latest/commands/role) commands output is scanned to discover replicas' addresses.\n\nThe problem is that the [`ROLE`](https://redis.io/docs/latest/commands/role) command, and the replication section of\nthe [`INFO`](https://redis.io/docs/latest/commands/info) output, when issued into a master instance, will show replicas\nas having the IP address they use to connect to the master, which, in\nenvironments using NAT may be different compared to the logical address of the\nreplica instance (the one that clients should use to connect to replicas).\n\nSimilarly the replicas will be listed with the listening port configured\ninto `redis.conf`, that may be different from the forwarded port in case\nthe port is remapped.\n\nTo fix both issues, it is possible, since Redis 3.2.2, to force\na replica to announce an arbitrary pair of IP and port to the master.\nThe two configurations directives to use are:\n\n    replica-announce-ip 5.5.5.5\n    replica-announce-port 1234\n\nAnd are documented in the example `redis.conf` of recent Redis distributions."
    },
    {
      "id": "the-info-and-role-command",
      "title": "The INFO and ROLE command",
      "role": "content",
      "text": "There are two Redis commands that provide a lot of information on the current\nreplication parameters of master and replica instances. One is [`INFO`](https://redis.io/docs/latest/commands/info). If the\ncommand is called with the `replication` argument as `INFO replication` only\ninformation relevant to the replication are displayed. Another more\ncomputer-friendly command is [`ROLE`](https://redis.io/docs/latest/commands/role), that provides the replication status of\nmasters and replicas together with their replication offsets, list of connected\nreplicas and so forth."
    },
    {
      "id": "partial-sync-after-restarts-and-failovers",
      "title": "Partial sync after restarts and failovers",
      "role": "content",
      "text": "Since Redis 4.0, when an instance is promoted to master after a failover,\nit will still be able to perform a partial resynchronization with the replicas\nof the old master. To do so, the replica remembers the old replication ID and\noffset of its former master, so can provide part of the backlog to the connecting\nreplicas even if they ask for the old replication ID.\n\nHowever the new replication ID of the promoted replica will be different, since it\nconstitutes a different history of the data set. For example, the master can\nreturn available and can continue accepting writes for some time, so using the\nsame replication ID in the promoted replica would violate the rule that a\nreplication ID and offset pair identifies only a single data set.\n\nMoreover, replicas - when powered off gently and restarted - are able to store\nin the `RDB` file the information needed to resync with their\nmaster. This is useful in case of upgrades. When this is needed, it is better to\nuse the [`SHUTDOWN`](https://redis.io/docs/latest/commands/shutdown) command in order to perform a `save & quit` operation on the\nreplica.\n\nIt is not possible to partially sync a replica that restarted via the\nAOF file. However the instance may be turned to RDB persistence before shutting\ndown it, than can be restarted, and finally AOF can be enabled again."
    },
    {
      "id": "maxmemory-on-replicas",
      "title": "`Maxmemory` on replicas",
      "role": "content",
      "text": "By default, a replica will ignore `maxmemory` (unless it is promoted to master after a failover or manually).\nIt means that the eviction of keys will be handled by the master, sending the DEL commands to the replica as keys evict in the master side.\n\nThis behavior ensures that masters and replicas stay consistent, which is usually what you want.\nHowever, if your replica is writable, or you want the replica to have a different memory setting, and you are sure all the writes performed to the replica are idempotent, then you may change this default (but be sure to understand what you are doing).\n\nNote that since the replica by default does not evict, it may end up using more memory than what is set via `maxmemory` (since there are certain buffers that may be larger on the replica, or data structures may sometimes take more memory and so forth).\nMake sure you monitor your replicas, and make sure they have enough memory to never hit a real out-of-memory condition before the master hits the configured `maxmemory` setting.\n\nTo change this behavior, you can allow a replica to not ignore the `maxmemory`. The configuration directives to use is:\n\n    replica-ignore-maxmemory no"
    }
  ],
  "examples": []
}