feat: add docs for failover

doc/toturial/03-Read-Write-Split & LoadBalancer.md

@@ -1,6 +1,10 @@
-# 
+# Introduction
 
-The goal of this tutorial is to explain how to enable read-write-splitting and load balancing functionality for WeSQL-Scale. WeSQL-Scale will parse statements to send write queries to the master server and distribute read queries for load balancing across the slave servers.
+WeSQL-Scale simplifies application logic by automatically routing read queries to read-only nodes and write queries to the read-write node. This is achieved by parsing and analyzing SQL statements, which improves load balancing and ensures efficient use of available resources.
+
+WeSQL-Scale also helps manage read-only nodes by routing queries to the appropriate node using various load balancing policies. This ensures that the workload is evenly distributed across all available nodes, optimizing performance and resource utilization.
+
+The goal of this tutorial is to explain how to enable read-write-splitting and load balancing functionality for WeSQL-Scale.
 
 # Setting through the set command.
 
@@ -41,19 +45,19 @@ vtgate \
 # Read-Write-Splitting Forwarding Rules
 
 - Only sent to the primary instance
-    - INSERT, UPDATE, DELETE, SELECT FOR UPDATE.
-    - All DDL operations (creating/dropping tables/databases, altering table structures, permissions, etc.).
-    - All requests within a transaction.
-    - Requests that use temporary tables.
-    - Requests that use GET_LOCK/RELEASE_LOCK/IS_USED_LOCK/RELEASE_ALL_LOCKS/IS_FREE_LOCK.
-    - SELECT last_insert_id() statements.
-    - All SHOW commands (preferably specifying a specific node).
-    - information_schema, performance_schema, mysql, sys databases.
-    - LOAD DATA statements.
+  - INSERT, UPDATE, DELETE, SELECT FOR UPDATE.
+  - All DDL operations (creating/dropping tables/databases, altering table structures, permissions, etc.).
+  - All requests within a transaction.
+  - Requests that use temporary tables.
+  - Requests that use GET_LOCK/RELEASE_LOCK/IS_USED_LOCK/RELEASE_ALL_LOCKS/IS_FREE_LOCK.
+  - SELECT last_insert_id() statements.
+  - All SHOW commands (preferably specifying a specific node).
+  - information_schema, performance_schema, mysql, sys databases.
+  - LOAD DATA statements.
 - Sent to read-only or primary instances
-    - SELECT statements outside of a transaction.
-    - COM_STMT_EXECUTE commands.
+  - SELECT statements outside of a transaction.
+  - COM_STMT_EXECUTE commands.
 - Only sent to VTGate layer
-    - All queries and modifications to User Variables.
-    - USE command.
-    - COM_STMT_PREPARE command.
+  - All queries and modifications to User Variables.
+  - USE command.
+  - COM_STMT_PREPARE command.

doc/toturial/04-Read-After-Write-Consistency.md

@@ -1,6 +1,8 @@
-# 
+# Introduction
 
-The goal of this tutorial is to explain how to enable the Read-After-Write-Consistency feature in WeSQL-Scale, in order to ensure that after enabling read-write separation, stale data will not be read.
+When an application writes data to the primary node and subsequently reads it on a read-only node, WeSQL-Scale makes sure that the data that was just written to the primary node can be accessed and read from the read-only node.
+
+The goal of this tutorial is to explain how to enable the Read-After-Write-Consistency feature in WeSQL-Scale.
 
 # Setting through the set command.
 
@@ -25,11 +27,4 @@ Currently, WeSQL-Scale supports these consistency levels:
 
 # Setting via launch parameters
 
-If you need to set the default value of read_write_splitting_policy, you can pass it as a startup parameter for the vtgate process:
-```bash
-vtgate \
-    # enable read-write-splitting and load balancing
-    --read_after_write_consistency session
-    # other necessary command line options
-    ...
-```
+If you need to set the default value of read_write_splitting_policy, you can pass it as a startup parameter for the vtgate process:

doc/toturial/05-Transparent Failover.md

@@ -0,0 +1,41 @@
+# 
+
+# Introduction
+
+Failover is a feature designed to ensure that if the original database instance becomes unavailable, it is replaced with another instance and remains highly available. Various factors can trigger a failover event, including issues with the database instance or scheduled maintenance procedures like database upgrades.
+
+Without WeSQL-Scale, a failover requires a short period of downtime. Existing connections to the database are disconnected and need to be reopened by your application. WeSQL-Scale is capable of automatically detecting failovers and buffering application SQL in its memory while keeping application connections intact, thus enhancing application resilience in the event of database failures.
+
+The goal of this tutorial is to explain how to enable the Transparent Failover feature of WeSQL-Scale.
+
+# Setting via launch parameters
+
+```
+vtgate \
+    # enable transparent failover
+    --enable_buffer
+    --buffer_size 10000
+    --buffer_window 30s
+    --buffer_max_failover_duration 60s
+    --buffer_min_time_between_failovers 60s
+    # other necessary command line options
+    ...
+
+```
+
+# Params Explained
+
+| enable_buffer | Enables buffering. Not enabled by default |
+| --- | --- |
+| buffer_size | Default: 10000 This should be sized to the appropriate number of expected request during a buffering event. Typically, if each connection has one request then, each connection will consume one buffer slot of the buffer_size and be put in a "pause" state as it is buffered on the vtgate. The resource considerations for setting this flag are memory resources. |
+| buffer_window | Default: 10s. The maximum time any individual request should be buffered for. Should probably be less than the value for --buffer_max_failover_duration. Adjust according to your application requirements. Be aware, if your MySQL client has write_timeout or read_timeout settings, those values should be greater than the buffer_max_failover_duration. |
+| buffer_max_failover_duration | Default: 20s. If buffering is active longer than this set duration, stop buffering and return errors to the client. |
+| buffer_min_time_between_failovers | Default 1m. If consecutive fail overs for a shard happens within less than this duration, do not buffer again. The purpose of this setting is to avoid consecutive fail over events where vtgate may be buffering, but never purging the buffer. |
+
+The two most important parameters are `buffer_window` and `buffer_max_failover_duration`.
+
+`buffer_window` controls how long each SQL can be buffered for at most.
+
+`buffer_max_failover_duration` controls how long the "Buffer feature" can last at most.
+
+If either of the two parameters times out, the corresponding SQL will be taken out of the buffer and executed.