From 5122d6c68eac1591fdadb47b6528a6e9ff0c2f82 Mon Sep 17 00:00:00 2001 From: iosmanthus Date: Tue, 14 Jun 2022 16:23:07 +0800 Subject: [PATCH 1/5] add docs for api v2 and tls reload Signed-off-by: iosmanthus --- 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 39070e9b254..94271f9e22a 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 SSL context, if a change detected, the SSL context will be rebuilded. +- default: `0`, means disable TLS context reload + +#### tikv.conn.recycle_time +- After `tikv.conn.recycle_time` (in seconds) with a TLS context reloading, the old connections will be forced to shutdown. +- 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 41ea6629425..7a3ddec1ad6 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 that allows the coexistence of transcation data and raw data. This feature could allow the [TiCDC](https://github.com/tikv/migration/tree/main/cdc) to capture the change of the data, and these events could be consumed by the downstream infrastructure like Kafka or another TiKV cluster for backup. + +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 enabel the API V2 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 denyed 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 From c85d0c10f5b3bf6f6b464470fa3269eb8b055690 Mon Sep 17 00:00:00 2001 From: iosmanthus Date: Tue, 14 Jun 2022 18:29:40 +0800 Subject: [PATCH 2/5] fix the default value tikv.tls.reload_interval Signed-off-by: iosmanthus --- docs/src/administration/configuration.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/src/administration/configuration.md b/docs/src/administration/configuration.md index 94271f9e22a..ecb8a58cd82 100644 --- a/docs/src/administration/configuration.md +++ b/docs/src/administration/configuration.md @@ -89,12 +89,12 @@ The following includes ThreadPool related parameters, which can be passed in thr - default: null #### tikv.tls.reload_interval -- The interval in seconds to poll the change of SSL context, if a change detected, the SSL context will be rebuilded. -- default: `0`, means disable TLS context reload +- The interval in seconds to poll the change of TLS context, if a change detected, the SSL context will be rebuilded. +- default: `"10s"`, `"0s"` means disable TLS context reload. #### tikv.conn.recycle_time - After `tikv.conn.recycle_time` (in seconds) with a TLS context reloading, the old connections will be forced to shutdown. -- default: `60s`. +- default: `"60s"`. #### tikv.rawkv.read_timeout_in_ms - RawKV read timeout in milliseconds. This parameter controls the timeout of `get` `getKeyTTL`. From 15f2a8e328f5a376823c93f1874308e48cff746e Mon Sep 17 00:00:00 2001 From: iosmanthus Date: Wed, 15 Jun 2022 00:40:41 +0800 Subject: [PATCH 3/5] add tikv.conn.recycle_time details Signed-off-by: iosmanthus --- docs/src/administration/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/administration/configuration.md b/docs/src/administration/configuration.md index ecb8a58cd82..5ec628a3817 100644 --- a/docs/src/administration/configuration.md +++ b/docs/src/administration/configuration.md @@ -93,7 +93,7 @@ The following includes ThreadPool related parameters, which can be passed in thr - default: `"10s"`, `"0s"` means disable TLS context reload. #### tikv.conn.recycle_time -- After `tikv.conn.recycle_time` (in seconds) with a TLS context reloading, the old connections will be forced to shutdown. +- After `tikv.conn.recycle_time` (in seconds) with a TLS context reloading, the old connections will be forced to shutdown preventing channel leak. - default: `"60s"`. #### tikv.rawkv.read_timeout_in_ms From 2691bca5edcd524dccbeecd3aa4df868f5a74a55 Mon Sep 17 00:00:00 2001 From: iosmanthus Date: Wed, 15 Jun 2022 14:29:14 +0800 Subject: [PATCH 4/5] apply suggestion about API V2 from pingyu Signed-off-by: iosmanthus --- docs/src/examples/rawkv.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/src/examples/rawkv.md b/docs/src/examples/rawkv.md index 7a3ddec1ad6..36562eb3411 100644 --- a/docs/src/examples/rawkv.md +++ b/docs/src/examples/rawkv.md @@ -52,7 +52,7 @@ public class Main { ## API V2 -With TiKV version >= 6.1.0, we release a new feature that allows the coexistence of transcation data and raw data. This feature could allow the [TiCDC](https://github.com/tikv/migration/tree/main/cdc) to capture the change of the data, and these events could be consumed by the downstream infrastructure like Kafka or another TiKV cluster for backup. +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 transaction data and raw data. 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. @@ -78,7 +78,7 @@ public class Main { ### Compatibility -The V2 Client should not access the cluster other than V2, this requires users to enabel the API V2 for the cluster: +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] @@ -87,7 +87,7 @@ enable-ttl = true api-version = 2 ``` -If V2 client accesses a V1 cluster or V1 cluster accesses a V2 cluster, the requests will be denyed by the cluster. You can check the compatibility via the following matrix. +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 | From 787402b6d2fbdbf6c43d2fd9e8af171eb9e827b4 Mon Sep 17 00:00:00 2001 From: iosmanthus Date: Wed, 15 Jun 2022 15:16:01 +0800 Subject: [PATCH 5/5] apply suggestion from xiaoguang Signed-off-by: iosmanthus --- docs/src/administration/configuration.md | 4 ++-- docs/src/examples/rawkv.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/src/administration/configuration.md b/docs/src/administration/configuration.md index 5ec628a3817..fd6fdca0a7e 100644 --- a/docs/src/administration/configuration.md +++ b/docs/src/administration/configuration.md @@ -89,11 +89,11 @@ The following includes ThreadPool related parameters, which can be passed in thr - default: null #### tikv.tls.reload_interval -- The interval in seconds to poll the change of TLS context, if a change detected, the SSL context will be rebuilded. +- 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 `tikv.conn.recycle_time` (in seconds) with a TLS context reloading, the old connections will be forced to shutdown preventing channel leak. +- 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 diff --git a/docs/src/examples/rawkv.md b/docs/src/examples/rawkv.md index 36562eb3411..182cc8d09c3 100644 --- a/docs/src/examples/rawkv.md +++ b/docs/src/examples/rawkv.md @@ -52,7 +52,7 @@ public class Main { ## 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 transaction data and raw data. Please refer to [v6.10 release notes](https://docs.pingcap.com/tidb/stable/release-6.1.0#ease-of-use) for detail. +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.