Skip to content

Commit 8e06824

Browse files
levkklevkk
authored
query routing docs (#45)
1 parent 6db51b4 commit 8e06824

File tree

1 file changed

+25
-0
lines changed

1 file changed

+25
-0
lines changed

‎README.md

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -133,6 +133,31 @@ All servers are checked with a `SELECT 1` query before being given to a client.
133133

134134
The ban time can be changed with `ban_time`. The default is 60 seconds.
135135

136+
Failover behavior can get pretty interesting (read complex) when multiple configurations and factors are involved. The table below will try to explain what PgCat does in each scenario:
137+
138+
| **Query** | **`SET SERVER ROLE TO`** | **`query_parser_enabled`** | **`primary_reads_enabled`** | **Target state** | **Outcome** |
139+
|---------------------------|--------------------------|----------------------------|-----------------------------|------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
140+
| Read query, i.e. `SELECT` | unset (any) | false | false | up | Query is routed to the first instance in the round-robin loop. |
141+
| Read query | unset (any) | true | false | up | Query is routed to the first replica instance in the round-robin loop. |
142+
| Read query | unset (any) | true | true | up | Query is routed to the first instance in the round-robin loop. |
143+
| Read query | replica | false | false | up | Query is routed to the first replica instance in the round-robin loop. |
144+
| Read query | primary | false | false | up | Query is routed to the primary. |
145+
| Read query | unset (any) | false | false | down | First instance is banned for reads. Next target in the round-robin loop is attempted. |
146+
| Read query | unset (any) | true | false | down | First replica instance is banned. Next replica instance is attempted in the round-robin loop. |
147+
| Read query | unset (any) | true | true | down | First instance (even if primary) is banned for reads. Next instance is attempted in the round-robin loop. |
148+
| Read query | replica | false | false | down | First replica instance is banned. Next replica instance is attempted in the round-robin loop. |
149+
| Read query | primary | false | false | down | The query is attempted against the primary and fails. The client receives an error. |
150+
| | | | | | |
151+
| Write query e.g. `INSERT` | unset (any) | false | false | up | The query is attempted against the first available instance in the round-robin loop. If the instance is a replica, the query fails and the client receives an error. |
152+
| Write query | unset (any) | true | false | up | The query is routed to the primary. |
153+
| Write query | unset (any) | true | true | up | The query is routed to the primary. |
154+
| Write query | primary | false | false | up | The query is routed to the primary. |
155+
| Write query | replica | false | false | up | The query is routed to the replica and fails. The client receives an error. |
156+
| Write query | unset (any) | true | false | down | The query is routed to the primary and fails. The client receives an error. |
157+
| Write query | unset (any) | true | true | down | The query is routed to the primary and fails. The client receives an error. |
158+
| Write query | primary | false | false | down | The query is routed to the primary and fails. The client receives an error. |
159+
| | | | | | |
160+
136161
### Sharding
137162
We use the `PARTITION BY HASH` hashing function, the same as used by Postgres for declarative partitioning. This allows to shard the database using Postgres partitions and place the partitions on different servers (shards). Both read and write queries can be routed to the shards using this pooler.
138163

0 commit comments

Comments
 (0)