TiKV in 5 Minutes

Get started using TiKV in 5 Minutes

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

Set up a local TiKV cluster with the default options
Monitor the TiKV cluster
Write data to and read data from the TiKV cluster
Stop and delete a TiKV cluster

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

Install TiUP by executing the following command:

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

Set the TiUP environment variables:
1. Redeclare the global environment variables:
```
source .bash_profile
```
2. Confirm whether TiUP is installed:
```
tiup
```
If TiUP is already installed, update the TiUP Playground component to the latest version:
```
tiup update --self && tiup update playground
```
Use TiUP Playground to start a local TiKV cluster. Before you do that, check your TiUP version using the following command:
```
tiup -v
```
- If your TiUP version is v1.5.2 or later, execute the following command to start a local TiKV cluster:
```
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:
```
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:

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.
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

Download the JAR files using the following commands:

curl -o tikv-client-java.jar https://github.com/tikv/client-java/releases/download/v3.2.0-rc/tikv-client-java-3.2.0-SNAPSHOT.jar -L && \
curl -o slf4j-api.jar https://repo1.maven.org/maven2/org/slf4j/slf4j-api/1.7.16/slf4j-api-1.7.16.jar

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

Try the RAW KV API.

Save the following script to the test_raw.java file.

import java.util.ArrayList;
import java.util.List;
import java.util.Optional;
import org.tikv.common.TiConfiguration;
import org.tikv.common.TiSession;
import org.tikv.kvproto.Kvrpcpb;
import org.tikv.raw.RawKVClient;
import org.tikv.shade.com.google.protobuf.ByteString;

TiConfiguration conf = TiConfiguration.createRawDefault("127.0.0.1:2379");
TiSession session = TiSession.create(conf);
RawKVClient client = session.createRawClient();

// put
client.put(ByteString.copyFromUtf8("k1"), ByteString.copyFromUtf8("Hello"));
client.put(ByteString.copyFromUtf8("k2"), ByteString.copyFromUtf8(","));
client.put(ByteString.copyFromUtf8("k3"), ByteString.copyFromUtf8("World"));
client.put(ByteString.copyFromUtf8("k4"), ByteString.copyFromUtf8("!"));
client.put(ByteString.copyFromUtf8("k5"), ByteString.copyFromUtf8("Raw KV"));

// get
Optional<ByteString> result = client.get(ByteString.copyFromUtf8("k1"));
System.out.println(result.get().toStringUtf8());

// batch get
List<Kvrpcpb.KvPair> list =client.batchGet(new ArrayList<ByteString>() {{
add(ByteString.copyFromUtf8("k1"));
add(ByteString.copyFromUtf8("k3"));
}});
System.out.println(list);

// scan
list = client.scan(ByteString.copyFromUtf8("k1"), ByteString.copyFromUtf8("k6"), 10);
System.out.println(list);

// close
client.close();
session.close();

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

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

The output is as follows:

Hello
[key: "k1"
value: "Hello"
, key: "k3"
value: "World"
]
[key: "k1"
value: "Hello"
, key: "k2"
value: ","
, key: "k3"
value: "World"
, key: "k4"
value: "!"
, key: "k5"
value: "Raw KV"
]

Use Python

Install the tikv-client python package.
```
pip3 install -i https://test.pypi.org/simple/ tikv-client
```
This package requires Python 3.5+.

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

Try the RAW KV API.

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

from tikv_client import RawClient

client = RawClient.connect("127.0.0.1:2379")

# put
client.put(b"k1", b"Hello")
client.put(b"k2", b",")
client.put(b"k3", b"World")
client.put(b"k4", b"!")
client.put(b"k5", b"Raw KV")

# get
print(client.get(b"k1"))

# batch get
print(client.batch_get([b"k1", b"k3"]))

# scan
print(client.scan(b"k1", end=b"k5", limit=10, include_start=True, include_end=True))

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

python3 test_raw.py

The output is as follows:

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

Try the TXN KV API.

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

from tikv_client import TransactionClient

client = TransactionClient.connect("127.0.0.1:2379")

# put
txn = client.begin()
txn.put(b"k1", b"Hello")
txn.put(b"k2", b",")
txn.put(b"k3", b"World")
txn.put(b"k4", b"!")
txn.put(b"k5", b"TXN KV")
txn.commit()

snapshot = client.snapshot(client.current_timestamp())

# get
print(snapshot.get(b"k1"))

# batch get
print(snapshot.batch_get([b"k1", b"k3"]))

# scan
print(snapshot.scan(b"k1", end=b"k5", limit=10, include_start=True, include_end=True))

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

python3 test_txn.py

The output is as follows:

b'Hello'
[(b'k3', b'World'), (b'k1', b'Hello')]
[(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.

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.
After the cluster is stopped, to delete the cluster, execute the following command:
```
tiup clean --all
```