From 7e6af2984de1f57b9b9391b127246329d0290abf Mon Sep 17 00:00:00 2001
From: iosmanthus <dengliming@pingcap.com>
Date: Wed, 15 Jun 2022 15:31:53 +0800
Subject: [PATCH] [close #610] [to #590] add docs for api v2 and tls reload
 (#611)

---
 docs/src/administration/configuration.md |  8 ++++
 docs/src/examples/rawkv.md               | 51 +++++++++++++++++++++++-
 2 files changed, 58 insertions(+), 1 deletion(-)

diff --git a/docs/src/administration/configuration.md b/docs/src/administration/configuration.md
index 39070e9b25..fd6fdca0a7 100644
--- a/docs/src/administration/configuration.md
+++ b/docs/src/administration/configuration.md
@@ -88,6 +88,14 @@ The following includes ThreadPool related parameters, which can be passed in thr
 - a PKCS#8 private key file in PEM format. e.g. /home/tidb/client-key.pem.
 - default: null
 
+#### tikv.tls.reload_interval
+- The interval in seconds to poll the change of TLS context, if a change is detected, the TLS context will be rebuilded.
+- default: `"10s"`, `"0s"` means disable TLS context reload.
+
+#### tikv.conn.recycle_time
+- After a TLS context reloading, the old connections will be forced to shutdown after `tikv.conn.recycle_time` to prevent channel leak.
+- default: `"60s"`.
+
 #### tikv.rawkv.read_timeout_in_ms
 - RawKV read timeout in milliseconds. This parameter controls the timeout of `get` `getKeyTTL`.
 - default: 2000 (2 seconds)
diff --git a/docs/src/examples/rawkv.md b/docs/src/examples/rawkv.md
index 41ea662942..182cc8d09c 100644
--- a/docs/src/examples/rawkv.md
+++ b/docs/src/examples/rawkv.md
@@ -48,4 +48,53 @@ public class Main {
     session.close();
   }
 }
-```
\ No newline at end of file
+```
+
+
+## API V2
+With TiKV version >= 6.1.0, we release a new feature called "TiKV API V2" which provides a new raw key-value storage format allowing the coexistence of RawKV and TxnKV. Please refer to [v6.10 release notes](https://docs.pingcap.com/tidb/stable/release-6.1.0#ease-of-use) for detail.
+
+To enable the API V2 mode, users need to specify the API version of the client.
+
+```java
+// import ...
+import org.tikv.common.TiConfiguration.ApiVersion;
+
+public class Main {
+  public static void main() {
+    TiConfiguration conf = TiConfiguration.createRawDefault("127.0.0.1:2379");
+    conf.setApiVersion(ApiVersion.V2);
+    try(TiSession session = TiSession.create(conf)) {
+      try(RawKVClient client = session.createRawClient()) {
+        // The client will read and write date in the format of API V2, which is
+        // transparent to the users.
+        client.put(ByteString.copyFromUtf8("hello"), ByteString.copyFromUtf8("world"));
+        // other client operations.
+      }
+    }
+  }
+}
+```
+
+### Compatibility
+
+The V2 Client should not access the cluster other than V2, this requires users to [enable the API V2](https://docs.pingcap.com/tidb/stable/tikv-configuration-file#api-version-new-in-v610) for the cluster:
+
+```toml
+[storage]
+# The V2 cluster must enable ttl for RawKV explicitly
+enable-ttl = true
+api-version = 2
+```
+
+If V2 client accesses a V1 cluster or V1 cluster accesses a V2 cluster, the requests will be denied by the cluster. You can check the compatibility via the following matrix.
+
+
+|                       | V1 Server | V1TTL Server | V2 Server |
+| --------------------- | --------- | ------------ | --------- |
+| V1 RawClient          | Raw       | Raw          | Error     |
+| V1 RawClient with TTL | Error     | Raw          | Error     |
+| V1 TxnClient          | Txn       | Error        | Error     |
+| V1 TiDB               | TiDB Data | Error        | TiDB Data |
+| V2 RawClient          | Error     | Error        | Raw       |
+| V2 TxnClient          | Error     | Error        | Txn       |
\ No newline at end of file