From 035bbc69135f8c882bbb420028aff7ccba34f105 Mon Sep 17 00:00:00 2001 From: Brandon Philips Date: Thu, 20 Feb 2014 15:32:23 -0800 Subject: [PATCH] feat(Documentation): add a section on consistent reads We have waited too long to document `consistent=true`. Document it! --- Documentation/api.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/Documentation/api.md b/Documentation/api.md index 6b67d4b66..a52d7f652 100644 --- a/Documentation/api.md +++ b/Documentation/api.md @@ -783,6 +783,17 @@ curl -L http://127.0.0.1:4001/v2/keys/ Here we see the `/message` key but our hidden `/_message` key is not returned. +### Read Consistency + +Followers in a cluster can be behind the leader in their copy of the keyspace. +If your application wants or needs the most up-to-date version of a key then it should ensure it reads from the current leader. +By using the `consistent=true` flag in your GET requests, etcd will make sure you are talking to the current master. + +As an example of how a machine can be behind the leader let's start with a three machine cluster: L, F1, and F2. +A client makes a write to L and F1 acknowledges the request. +The client is told the write was successful and the keyspace is updated. +Meanwhile F2 has partitioned from the network and will have an out-of-date version of the keyspace until the partition resolves. +Since F2 missed the most recent write, a client reading from F2 will have an out-of-date version of the keyspace. ## Lock Module