This tutorial provides you a quick way to get started with TiKV, including the following operations:

Prerequisites

Before you start, ensure that you are using macOS or Linux.

This quick-start tutorial is only for test environments. For production environments, refer to Install TiKV.

Set up a local TiKV cluster with the default options

  1. Install TiUP by executing the following command:

    1. curl --proto '=https' --tlsv1.2 -sSf https://tiup-mirrors.pingcap.com/install.sh | sh

  2. Set the TiUP environment variables:

    1. Redeclare the global environment variables:

      1. source .bash_profile

    2. Confirm whether TiUP is installed:

      1. tiup

  3. If TiUP is already installed, update the TiUP Playground component to the latest version:

    1. tiup update --self && tiup update playground

  4. Use TiUP Playground to start a local TiKV cluster. Before you do that, check your TiUP version using the following command:

    1. tiup -v

    • If your TiUP version is v1.5.2 or later, execute the following command to start a local TiKV cluster:

      1. tiup playground --mode tikv-slim

    • If your TiUP version is earlier than v1.5.2, execute the following command to start a local TiKV cluster:

      1. tiup playground

    Refer to TiUP playground document for more TiUP Playground commands.

Monitor the TiKV cluster

After the TiKV cluster is started using TiUP Playground, to monitor the cluster metrics, perform the following steps:

  1. Open your browser, access http://127.0.0.1:3000, and then log in to the Grafana Dashboard.

    By default, the username is admin and the password is admin.

  2. Open the TiKV-Summary page on the Grafana Dashboard and find the monitoring metrics of your TiKV cluster.

Write data to and read data from the TiKV cluster

To write to and read from the TiKV cluster, you can use Java, Go, Rust, C, or Python script.

The following two examples use Java and Python respectively to show how to write “Hello World!” to TiKV.

Use Java

  1. Download the JAR files using the following commands:

    1. curl -o tikv-client-java.jar https://download.pingcap.org/tikv-client-java-3.2.0-SNAPSHOT.jar && \
    2. curl -o slf4j-api.jar https://repo1.maven.org/maven2/org/slf4j/slf4j-api/1.7.16/slf4j-api-1.7.16.jar

  2. Install jshell. The JDK version should be 9.0 or later.

  3. Try the RAW KV API.

    1. Save the following script to the test_raw.java file.

      1. import java.util.ArrayList;
      2. import java.util.List;
      3. import java.util.Optional;
      4. import org.tikv.common.TiConfiguration;
      5. import org.tikv.common.TiSession;
      6. import org.tikv.kvproto.Kvrpcpb;
      7. import org.tikv.raw.RawKVClient;
      8. import org.tikv.shade.com.google.protobuf.ByteString;
      10. TiConfiguration conf = TiConfiguration.createRawDefault("127.0.0.1:2379");
      11. TiSession session = TiSession.create(conf);
      12. RawKVClient client = session.createRawClient();
      14. // put
      15. client.put(ByteString.copyFromUtf8("k1"), ByteString.copyFromUtf8("Hello"));
      16. client.put(ByteString.copyFromUtf8("k2"), ByteString.copyFromUtf8(","));
      17. client.put(ByteString.copyFromUtf8("k3"), ByteString.copyFromUtf8("World"));
      18. client.put(ByteString.copyFromUtf8("k4"), ByteString.copyFromUtf8("!"));
      19. client.put(ByteString.copyFromUtf8("k5"), ByteString.copyFromUtf8("Raw KV"));
      21. // get
      22. Optional<ByteString> result = client.get(ByteString.copyFromUtf8("k1"));
      23. System.out.println(result.get().toStringUtf8());
      25. // batch get
      26. List<Kvrpcpb.KvPair> list =client.batchGet(new ArrayList<ByteString>() {{
      27. add(ByteString.copyFromUtf8("k1"));
      28. add(ByteString.copyFromUtf8("k3"));
      29. }});
      30. System.out.println(list);
      32. // scan
      33. list = client.scan(ByteString.copyFromUtf8("k1"), ByteString.copyFromUtf8("k6"), 10);
      34. System.out.println(list);
      36. // close
      37. client.close();
      38. session.close();

    2. Run the test_raw.java script to write “Hello World!” to TiKV:

      1. jshell --class-path tikv-client-java.jar:slf4j-api.jar --startup test_raw.java

      The output is as follows:

      1. Hello
      2. [key: "k1"
      3. value: "Hello"
      4. , key: "k3"
      5. value: "World"
      6. ]
      7. [key: "k1"
      8. value: "Hello"
      9. , key: "k2"
      10. value: ","
      11. , key: "k3"
      12. value: "World"
      13. , key: "k4"
      14. value: "!"
      15. , key: "k5"
      16. value: "Raw KV"
      17. ]

Use Python

  1. Install the tikv-client python package.

    1. pip3 install -i https://test.pypi.org/simple/ tikv-client

    This package requires Python 3.5+.

  2. Use either the RAW KV API or TXN KV API to write data to TiKV.

    • Try the RAW KV API.

      1. Save the following Python script to the test_raw.py file.

        1. from tikv_client import RawClient
        3. client = RawClient.connect("127.0.0.1:2379")
        5. # put
        6. client.put(b"k1", b"Hello")
        7. client.put(b"k2", b",")
        8. client.put(b"k3", b"World")
        9. client.put(b"k4", b"!")
        10. client.put(b"k5", b"Raw KV")
        12. # get
        13. print(client.get(b"k1"))
        15. # batch get
        16. print(client.batch_get([b"k1", b"k3"]))
        18. # scan
        19. print(client.scan(b"k1", end=b"k5", limit=10, include_start=True, include_end=True))

      2. Run the test_raw.py script to write “Hello World!” to TiKV:

        1. python3 test_raw.py

        The output is as follows:

        1. b'Hello'
        2. [(b'k3', b'World'), (b'k1', b'Hello')]
        3. [(b'k1', b'Hello'), (b'k2', b','), (b'k3', b'World'), (b'k4', b'!'), (b'k5', b'Raw KV')]

    • Try the TXN KV API.

      1. Save the following Python script to the test_txn.py file.

        1. from tikv_client import TransactionClient
        3. client = TransactionClient.connect("127.0.0.1:2379")
        5. # put
        6. txn = client.begin()
        7. txn.put(b"k1", b"Hello")
        8. txn.put(b"k2", b",")
        9. txn.put(b"k3", b"World")
        10. txn.put(b"k4", b"!")
        11. txn.put(b"k5", b"TXN KV")
        12. txn.commit()
        14. snapshot = client.snapshot(client.current_timestamp())
        16. # get
        17. print(snapshot.get(b"k1"))
        19. # batch get
        20. print(snapshot.batch_get([b"k1", b"k3"]))
        22. # scan
        23. print(snapshot.scan(b"k1", end=b"k5", limit=10, include_start=True, include_end=True))

      2. Run the test_txn.py script to write “Hello World!” to TiKV:

        1. python3 test_txn.py

        The output is as follows:

        1. b'Hello'
        2. [(b'k3', b'World'), (b'k1', b'Hello')]
        3. [(b'k1', b'Hello'), (b'k2', b','), (b'k3', b'World'), (b'k4', b'!'), (b'k5', b'TXN KV')]

Stop and delete the TiKV cluster

If you do not need the local TiKV cluster anymore, you can stop and delete it.

  1. To stop the TiKV cluster, get back to the terminal session in which you have started the TiKV cluster. Press Ctrl + C and wait for the cluster to stop.

  2. After the cluster is stopped, to delete the cluster, execute the following command:

    1. tiup clean --all