From 84c24ac0b9ec1c6aca9da810e721a3e38dc993b6 Mon Sep 17 00:00:00 2001 From: Lev Kokotov Date: Sat, 5 Feb 2022 13:39:33 -0800 Subject: [PATCH] docs --- README.md | 36 +++++++++++++++++++++++++++++++++++- 1 file changed, 35 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index c262eac..09e090a 100644 --- a/README.md +++ b/README.md @@ -25,10 +25,44 @@ pgbench -t 1000 -p 5433 -h 127.0.0.1 --protocol extended 2. Transaction mode (basic). 3. `COPY` protocol support. 4. Query cancellation. +5. Round-robin load balancing of replicas. +6. Banlist & failover + +### Session mode +Each client owns its own server for the duration of the session. Commands like `SET` are allowed. +This is identical to PgBouncer session mode. + +### Transaction mode +The connection is attached to the server for the duration of the transaction. `SET` will pollute the connection, +but `SET LOCAL` works great. Identical to PgBouncer transaction mode. + +### COPY protocol +That one isn't particularly special, but good to mention that you can `COPY` data in and from the server +using this pooler. + +### Query cancellation +Okay, this is just basic stuff, but we support cancelling queries. If you know the Postgres protocol, +this might be relevant given than this is a transactional pooler but if you're new to Pg, don't worry about it, it works. + +### Round-robin load balancing +This is the novel part. PgBouncer doesn't support it and suggests we use DNS of a TCP proxy instead. +We prefer to have everything as part of one package; arguably, it's easier to understand and optimize. +This pooler will round-robin between multiple replicas keeping load reasonably even. + +### Banlist & failover +This is where it gets even more interesting. If we fail to connect to one of the replicas or it fails a health check, +we add it to a ban list. No more new transactions will be served by that replica for, in our case, 60 seconds. This +gives it the opportunity to recover while clients are happily served by the remaining replicas. + +This decreases error rates substantially! Worth noting here that on busy systems, if the replicas are running too hot, +failing over could bring even more load and tip over the remaining healthy-ish replicas. In this case, a decision should be made: +either lose 1/x of your traffic or risk losing it all eventually. Ideally you overprovision your system, so you don't necessarily need +to make this choice :-). + ## Missing -1. All the features I promised above. Will make them soon, promise :-). +1. Sharding. Soon :-). 2. Authentication, ehem, this proxy is letting anyone in at the moment. ## Benchmarks