PS-9822 Improve documentation on MyRocks variables (8.0)

docs/variables.md

@@ -269,8 +269,18 @@ Enabled by default.
 | Data type    | Boolean                                   |
 | Default      | OFF                                       |
 
-Specifies whether to allow multiple writers to update memtables in parallel.
-Disabled by default.
+#### Enable concurrent memtable writes
+
+This option is a direct bridge to RocksDB's `DBOptions::allow_concurrent_memtable_write`. If this setting is not enabled, MyRocks processes memtable updates sequentially, even when multiple threads issue writes simultaneously. Enabling this option allows parallel memtable updates, which can improve write throughput in multi-threaded workloads.
+
+#### When to enable
+
+This setting is disabled by default. Consider enabling rocksdb_allow_concurrent_memtable_write in the following situations:
+
+| Condition                   | Description |
+|----------------------------|-------------|
+| High concurrent write workload | Your application has many threads or clients writing to MyRocks at the same time. Enabling this option can improve throughput and reduce latency in multi-threaded environments. |
+| Write-bound workloads          | If write performance is a bottleneck and CPU usage is low during writes, it may be due to serialized memtable updates. Enabling this option allows better use of CPU cores and can improve overall write performance. |
 
 ### `rocksdb_allow_to_start_after_corruption`
 
@@ -1092,11 +1102,27 @@ By default, it is created in the current working directory.
 | Data type    | Numeric                        |
 | Default      | 0                              |
 
-Specifies the maximum size of all memtables used to store writes in MyRocks
-across all column families. When this size is reached, the data is flushed
-to persistent media.
-The default value is `0`.
-The allowed range is up to `18446744073709551615`.
+This option is a direct bridge to RocksDB's `DBOptions::db_write_buffer_size`. 
+
+The `rocksdb_db_write_buffer_size` setting limits the amount of memory in memtables across all column families. MyRocks flushes the largest memtable to disk when the total size exceeds this limit. This operation helps prevent excessive memory use and makes memory behavior more predictable.
+
+#### Available values
+
+The default value is `0`, which is disabled, and MyRocks does not limit the amount of memory used by memtables.
+
+Setting a non-zero value provides a safeguard against excessive memory usage. It ensures that the total memory used by memtables does not exceed the specified limit, preventing potential memory overflow issues.
+
+The maximum range is `18446744073709551615`.
+
+#### When to use
+
+This setting is disabled by default.  You should consider setting rocksdb_db_write_buffer_size under the following conditions:
+
+	•	Running multiple column families and controlling overall memory usage.
+
+	•	Operating in shared environments or low-memory systems.
+
+	•	Avoiding Out-of-Memory (OOM) issues in write-heavy workloads.
 
 ### `rocksdb_deadlock_detect`
 
@@ -1488,11 +1514,30 @@ The variable was implemented in [Percona Server for MySQL 8.0.20-11](release-not
 | Data type    | Boolean                          |
 | Default      | OFF                              |
 
+#### Version changes
+
 The variable was implemented in [Percona Server for MySQL 8.0.25-15](release-notes/Percona-Server-8.0.25-15.md#id1).
 
-DBOptions::enable_pipelined_write for RocksDB.
+#### Improving Write Throughput with Pipelined Writes
+
+This option maps directly to RocksDB’s `DBOptions::enable_pipelined_write`. For details, see the [RocksDB documentation on Pipelined Write](https://github.com/facebook/rocksdb/wiki/Pipelined-Write).
+
+In database systems, concurrency means that multiple operations can run simultaneously. By default, write operations are handled in order using a single thread queue. The first thread in line becomes the leader and performs the write to both the Write-Ahead Log (WAL) and the memtable, one after the other. This setup limits the number of writes that can happen simultaneously.
+
+The pipelined write feature allows WAL and memtable writes to happen in parallel. When `rocksdb_enable_pipelined_write` is set to `ON`, RocksDB uses separate threads for writing to the Write-Ahead Log (WAL) and the memtable. A thread waits in the WAL queue and then moves to the memtable queue. In the WAL queue, each thread waits only for earlier WAL writes to finish. They do not wait for memtable updates.
+
+This setup allows WAL and memtable operations to run in parallel. It improves write throughput and can reduce latency during the prepare phase of a two phase commit.
+
+#### When to enable pipelined writes
+
+Pipelined writes are disabled by default. You should consider enabling enable_pipelined_write in MyRocks under the following conditions:
 
-If `enable_pipelined_write` is `ON`, a separate write thread is maintained for WAL write and memtable write. A write thread first enters the WAL writer queue and then the memtable writer queue. A pending thread on the WAL writer queue only waits for the previous WAL write operations but does not wait for memtable write operations. Enabling the feature may improve write throughput and reduce latency of the prepare phase of a two-phase commit.
+| Condition                          | Description                                                                                                                       |
+|------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|
+| High concurrent write workloads    | If your application involves many concurrent writers, pipelined writes, which overlap WAL and memtable writes, can improve throughput. |
+| Write-Ahead logging (WAL) is enabled | This feature only applies when WAL is enabled. Enabling pipelined writes has no effect if you’re not using WAL.                  |
+| Lower latency for transactions | Particularly beneficial in reducing latency during the prepare phase of two-phase commits (2PC), which is critical in transactional workloads. |
+| WAL writes are a bottleneck        | If profiling shows that waiting for WAL writes limits your write throughput, pipelined writes can help by decoupling WAL and memtable operations. |
 
 ### `rocksdb_enable_remove_orphaned_dropped_cfs`