Clarify request forwarding policies
@@ -111,7 +111,15 @@ curl -XPOST 'localhost:4001/db/execute?pretty&timings' -H "Content-Type: applica
```
## Sending requests to followers
-If you send a HTTP request to a node that is not the leader of the cluster, and do not specify `none` as the [read-consistency level](https://github.com/rqlite/rqlite/blob/master/doc/CONSISTENCY.md), the node will respond with [HTTP 301 Moved Permanently](https://en.wikipedia.org/wiki/HTTP_301) and include the address of the leader as the `Location` header in the response. For example:
+What happens when you send a request to a follower depends on the nature of the request.
+
+You must always send write-requests (requests will change the database) to the leader. If you send a write-request to a follower, the follower will respond with [HTTP 301 Moved Permanently](https://en.wikipedia.org/wiki/HTTP_301) and include the address of the leader as the `Location` header in the response.
+
+The situation for queries -- requests which just read data -- is somewhat different. If you send the request to a node that is not the leader of the cluster, and specify `strong` or `weak` as the [read-consistency level](https://github.com/rqlite/rqlite/blob/master/doc/CONSISTENCY.md), the node will also respond with [HTTP 301 Moved Permanently](https://en.wikipedia.org/wiki/HTTP_301) and include the address of the leader as the `Location` header in the response.
+
+However, if you specify `none` for read-consistency the node will query its local node SQLite database. No redirect will be returned.
+
+## Example of redirect on query
```
$ curl -v -G 'localhost:4003/db/query?pretty&timings' --data-urlencode 'q=SELECT * FROM foo'
* Trying ::1...
@@ -136,9 +144,7 @@ $ curl -v -G 'localhost:4003/db/query?pretty&timings' --data-urlencode 'q=SELECT
```
It is up the clients to re-issue the command to the leader.
-This choice was made, as it provides maximum visibility to the clients. For example, if a follower transparently forwarded the request to the leader, and one of the nodes then crashed during processing, it may be much harder for the client to determine where in the chain of nodes the processing failed.
-
-If you do specify `none` for read-consistency however, the node will request its local node SQLite database. No redirect will be returned.
+This choice was made, as it provides maximum visibility to the clients. For example, if a follower transparently forwarded a request to the leader, and one of the nodes then crashed during processing, it may be much harder for the client to determine where in the chain of nodes the processing failed.
## Bulk API
You can learn about the bulk API [here](https://github.com/rqlite/rqlite/blob/master/doc/BULK.md).
