content/en/docs/19.0: vtgate partial shard commit warnings (vitessio#…

…1655) * content/en/docs/19.0: vtgate partial shard commit warnings Signed-off-by: Max Englander <max@planetscale.com> * make it look nicer Signed-off-by: Max Englander <max@planetscale.com> * document --warn-non-atomic-commit flag Signed-off-by: Max Englander <max@planetscale.com> --------- Signed-off-by: Max Englander <max@planetscale.com>
rohan-flutterint · Feb 7, 2024 · 23dfbaf · 23dfbaf
1 parent 3e41f71
commit 23dfbaf
Show file tree

Hide file tree

Showing 2 changed files with 14 additions and 0 deletions.
diff --git a/content/en/docs/19.0/reference/programs/vtgate/_index.md b/content/en/docs/19.0/reference/programs/vtgate/_index.md
@@ -253,6 +253,7 @@ vtgate \
       --warming-reads-concurrency int                                    Number of concurrent warming reads allowed (default 500)
       --warming-reads-percent int                                        Percentage of reads on the primary to forward to replicas. Useful for keeping buffer pools warm
       --warming-reads-query-timeout duration                             Timeout of warming read queries (default 5s)
+      --warn-non-atomic-commit                                           If a multi-shard commit fails after successfully committing to one or more shards, a warning will be added to the session.
       --warn_memory_rows int                                             Warning threshold for in-memory results. A row count higher than this amount will cause the VtGateWarnings.ResultsExceeded counter to be incremented. (default 30000)
       --warn_payload_size int                                            The warning threshold for query payloads in bytes. A payload greater than this threshold will cause the VtGateWarnings.WarnPayloadSizeExceeded counter to be incremented.
       --warn_sharded_only                                                If any features that are only available in unsharded mode are used, query execution warnings will be added to the session

diff --git a/...nt/en/docs/19.0/user-guides/configuration-advanced/shard-isolation-atomicity.md b/...nt/en/docs/19.0/user-guides/configuration-advanced/shard-isolation-atomicity.md
@@ -137,6 +137,19 @@ By default, Vitess employs a default setting for `transaction_mode` of **MULTI**
   * Phase 2:  Issue the subset of inserts for each shard. This is also done in parallel. An error at this point will allow us to rollback the transactions on the shards.  Again, no data has been affected, and the application can retry.
   * Phase 3:  Issue commits against each shard involved in the insert. This is done serially.  This allows the operation to halt if there is an error on one of the shards.  At this point an error would be returned to the application, **but the inserts on shards committed before the failing shard cannot be rolled back**. As a result the atomicity of the insert is broken, and now clients will see (possibly permanently) inconsistent results. It is left up to the client to repair the possible inconsistency, potentially with a retry, or some more elaborate mechanism.
 
+VTGate can be configured, with `--warn-non-atomic-commit`, to record a warning and increment a counter when a commit error occurs on one shard after successfully committing to other shard(s). The warnings will look like this:
+
+``` mysql
+mysql> show warnings;
++---------+------+-----------------------------------------------------+
+| Level   | Code | Message                                             |
++---------+------+-----------------------------------------------------+
+| Warning |  301 | multi-db commit failed after committing to 1 shards |
++---------+------+-----------------------------------------------------+
+1 row in set, 1 warning (0.00 sec)
+```
+<br>
+
 #### Notes: 
 
 * As an optimization Phase 1+2 are performed at the same time, see below.