This page introduces what’s TiKV API v2 and how to use it.

TiKV API v2

Before TiKV v6.1.0, RawKV interfaces just store the raw data from clients, so it only provides basic read/write ability of key-values. Besides, due to different encoding and lacking of isolation, TiDB, TxnKV, and RawKV can not be used simultaneously in the same TiKV cluster. In this scenario, multiple clusters must be deployed, and make costs of resource and maintenance increase.

TiKV API v2 provides new storage format, including:

  • RawKV organizes data as MVCC, records update timestamp of every entry, and provides CDC feature based on the timestamp (RawKV CDC is an experimental feature provided by another component, see TiKV-CDC).
  • Data in TiKV is separated by modes, supports using TiDB, TxnKV, and RawKV in a single cluster at the same time.
  • Key Space field is reserved, to support multi-tenant in the future.

To use TiKV API v2, please add or modify api-version = 2 & enable-ttl = true in [storage] section of TiKV. See configuration file for detail.

Besides, when API V2 is enabled, you need to deploy at least one tidb-server instance to reclaim expired data of MVCC. To ensure high availability, you can deploy multiple tidb-server instances. Note that these tidb-server instances can also be used as normal TiDB database.

Warning

  • Due to the significant change on storage format, only if the existing TiKV cluster is empty or storing only TiDB data, you can enable or disable API v2 smoothly. In other scenario, you must deploy a new cluster, and migrate data using TiKV-BR.
  • After API V2 is enabled, you cannot downgrade the TiKV cluster to a version earlier than v6.1.0. Otherwise, data corruption might occur.

Usage Demonstration

Prerequisites

Before you start, ensure that you have installed TiUP according to TiKV in 5 Minutes.

Step 1: Config TiKV to enable API v2

To enable API v2, create a file tikv.yaml using the following configuration.

  1. [storage]
  2. api-version = 2
  3. enable-ttl = true

Step 2: Start TiKV Cluster

  1. tiup playground nightly --db 1 --tiflash 0 --pd 1 --kv 1 --kv.config tikv.yaml

Step 3: Write the code to test API v2

Take Go client as example, save the following script to file test_api_v2.go.

  1. package main
  3. import (
  4.     "context"
  5.     "fmt"
  7.     "github.com/pingcap/kvproto/pkg/kvrpcpb"
  8.     "github.com/tikv/client-go/v2/rawkv"
  9. )
  11. func main() {
  12.     cli, err := rawkv.NewClientWithOpts(context.TODO(), []string{"127.0.0.1:2379"},
  13.         rawkv.WithAPIVersion(kvrpcpb.APIVersion_V2))
  14.     if err != nil {
  15.         panic(err)
  16.     }
  17.     defer cli.Close()
  19.     fmt.Printf("cluster ID: %d\n", cli.ClusterID())
  21.     key := []byte("Company")
  22.     val := []byte("PingCAP")
  24.     // put key into tikv
  25.     err = cli.Put(context.TODO(), key, val)
  26.     if err != nil {
  27.         panic(err)
  28.     }
  29.     fmt.Printf("Successfully put %s:%s to tikv\n", key, val)
  31.     // get key from tikv
  32.     val, err = cli.Get(context.TODO(), key)
  33.     if err != nil {
  34.         panic(err)
  35.     }
  36.     fmt.Printf("found val: %s for key: %s\n", val, key)
  38.     // delete key from tikv
  39.     err = cli.Delete(context.TODO(), key)
  40.     if err != nil {
  41.         panic(err)
  42.     }
  43.     fmt.Printf("key: %s deleted\n", key)
  45.     // get key again from tikv
  46.     val, err = cli.Get(context.TODO(), key)
  47.     if err != nil {
  48.         panic(err)
  49.     }
  50.     fmt.Printf("found val: %s for key: %s\n", val, key)
  51. }

Step 4: Run the code

  1. ❯ go mod tidy
  2. ❯ go run test_api_v2.go
  3. [2022/11/02 21:23:10.507 +08:00] [INFO] [client.go:405] ["[pd] create pd client with endpoints"] [pd-address="[172.16.5.32:32379]"]
  4. [2022/11/02 21:23:10.513 +08:00] [INFO] [base_client.go:378] ["[pd] switch leader"] [new-leader=http://172.16.5.32:32379] [old-leader=]
  5. [2022/11/02 21:23:10.513 +08:00] [INFO] [base_client.go:105] ["[pd] init cluster id"] [cluster-id=7153087019074699621]
  6. [2022/11/02 21:23:10.514 +08:00] [INFO] [client.go:698] ["[pd] tso dispatcher created"] [dc-location=global]
  7. cluster ID: 7153087019074699621
  8. Successfully put Company:PingCAP to tikv
  9. found val: PingCAP for key: Company
  10. key: Company deleted
  11. found val:  for key: Company
  12. [2022/11/02 21:23:10.532 +08:00] [INFO] [client.go:779] ["[pd] stop fetching the pending tso requests due to context canceled"] [dc-location=global]
  13. [2022/11/02 21:23:10.533 +08:00] [INFO] [client.go:716] ["[pd] exit tso dispatcher"] [dc-location=global]