Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

*: add TiKV overview, installation, and client driver #472

Merged
merged 12 commits into from
May 31, 2018
Merged

*: add TiKV overview, installation, and client driver #472

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
a449dff
*: add TiKV Quick Start Guide
lilin90 May 21, 2018
88582f2
tikv: update code display effect
lilin90 May 21, 2018
057f6a8
tikv: update the ParseInt code
lilin90 May 22, 2018
e514dec
tikv: fix a step typo
lilin90 May 23, 2018
d288385
tikv: update wording
lilin90 May 28, 2018
32d3fd8
tikv, readme: reorganize TiKV documents
lilin90 May 28, 2018
41125a8
tikv, readme: reorganize the structure and update content based on co…
lilin90 May 29, 2018
cd06eff
tikv, readme: add Install TiKV Using Docker Compose
lilin90 May 29, 2018
f09c7fc
tikv: add two links to API usage
lilin90 May 29, 2018
b11fe3a
tikv, readme: update file name and readme
lilin90 May 31, 2018
e1b5863
tikv: update wording
lilin90 May 31, 2018
97162db
tikv: update two links
lilin90 May 31, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
tikv, readme: reorganize TiKV documents
  • Loading branch information
@lilin90
lilin90 committed May 28, 2018
commit 32d3fd888d50ecabd87562490d5b3a4a45fd2976
8 changes: 7 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -112,7 +112,13 @@
- [TiKV Control](tools/tikv-control.md)
- [TiDB Controller](tools/tidb-controller.md)
+ TiKV
- [TiKV Quick Start Guide](tikv/tikv-quick-start-guide.md)
+ Get Started
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I prefer removing "Get started"

- [Overview](tikv/get-started/tikv-overview.md)
+ Install TiKV
- [Prerequisites](op-guide/recommendation.md)
- [Install TiKV Using Binary Files](tikv/get-started/install-tikv-using-binary.md)
+ Client Drivers
- [Go](tikv/get-started/go-client-api.md)
+ TiSpark
- [Quick Start Guide](tispark/tispark-quick-start-guide.md)
- [User Guide](tispark/tispark-user-guide.md)
Expand Down
204 changes: 10 additions & 194 deletions tikv/tikv-quick-start-guide.md → tikv/get-started/go-client-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,199 +1,15 @@
---
title: TiKV Quick Start Guide
category: quick start
title: Try Two Types of APIs
category: user guide
---

# TiKV Quick Start Guide
# Try Two Types of APIs

TiKV (The pronunciation is: /'taɪkeɪvi:/ tai-K-V, etymology: titanium) is a distributed Key-Value database which is based on the design of Google Spanner and HBase, but it is much simpler without dependency on any distributed file system.
To apply to different scenarios, TiKV provides [two types of APIs](tikv-overview.md#two-types-of-apis) for developers: the Raw Key-Value API and the Transactional Key-Value API. This document guides you through how to use the two APIs in TiKV using two examples.

As the storage layer of TiDB, TiKV can work separately and does not depend on the SQL layer of TiDB. TiKV provides two APIs for developers: the Raw Key-Value API and the Transactional Key-Value API.
The usage examples are based on the [deployment of TiKV on multiple nodes for test](install-tikv.md#deploy-the-tikv-cluster-on-multiple-nodes-for-test). You can also quickly try the two types of APIs on a single machine.

This guide describes how to quickly deploy a TiKV cluster on a single machine and how to use the TiKV cluster through APIs written in Go.

The TiKV server software stack is as follows:

![The TiKV software stack](../media/tikv_stack.png)

## Prepare

TiKV can be deployed in the Intel architecture server and major virtualization environments, and it supports most of the major hardware networks and Linux operating systems.

Currently, TiKV provides two APIs: the Raw Key-Value API and the Transactional Key-Value API. This guide uses the APIs written in Go. To write the API, you need to install Go:

- Make sure ​Go​ (version 1.8+) is installed.
- Ensure your `$GOPATH` is set. (For example, `export GOPATH=$HOME/go`)

## Deploy the TiKV cluster

TiKV provides the official binary installation package that supports Linux.

- To quickly understand and try TiKV, see [Deploy the TiKV cluster on a single machine](#deploy-the-tikv-cluster-on-a-single-machine).
- To try TiKV out and explore the features, see [Deploy the TiKV cluster on multiple nodes for test](#deploy-the-tikv-cluster-on-multiple-nodes-for-test).

### Deploy the TiKV cluster on a single machine

This section describes how to deploy 1 PD instance and 3 TiKV instances on a single machine installed with the Linux system.

> **Note:**
>
> - For the production environment, it is recommended to use multiple nodes cluster deployment. Before you begin, see [Software and Hardware Requirements](op-guide/recommendation.md).
> - Before starting the process, make sure the result of `ulimit -n` is large enough. It is recommended to set the value to `unlimited` or larger than 1000000.

To deploy a TiKV cluster on a single machine for test, take the following steps:

1. Download the official binary package.

```bash
# Download the package.
wget https://download.pingcap.org/tidb-latest-linux-amd64.tar.gz
wget http://download.pingcap.org/tidb-latest-linux-amd64.sha256

# Check the file integrity. If the result is OK, the file is correct.
sha256sum -c tidb-latest-linux-amd64.sha256

# Extract the package.
tar -xzf tidb-latest-linux-amd64.tar.gz
cd tidb-latest-linux-amd64
```

2. Start PD.

```bash
./bin/pd-server --name=pd1 \
--data-dir=pd1 \
--client-urls="http://127.0.0.1:2379" \
--peer-urls="http://127.0.0.1:2380" \
--initial-cluster="pd1=http://127.0.0.1:2380" \
--log-file=pd1.log
```

3. Start TiKV.

To start the 3 TiKV instances, open a new terminal tab or window, come to the `tidb-latest-linux-amd64` directory, and start the instances using the following command:

```bash
./bin/tikv-server --pd-endpoints="127.0.0.1:2379" \
--addr="127.0.0.1:20160" \
--data-dir=tikv1 \
--log-file=tikv1.log

./bin/tikv-server --pd-endpoints="127.0.0.1:2379" \
--addr="127.0.0.1:20161" \
--data-dir=tikv2 \
--log-file=tikv2.log

./bin/tikv-server --pd-endpoints="127.0.0.1:2379" \
--addr="127.0.0.1:20162" \
--data-dir=tikv3 \
--log-file=tikv3.log
```

You can use the [pd-ctl](https://github.com/pingcap/pd/tree/master/pdctl) tool to verify whether PD and TiKV are successfully deployed:

```
./bin/pd-ctl store -d -u http://127.0.0.1:2379
```

To access the data in TiKV, you can [try TiKV using the Raw Key-Value API and Transactional Key-Value API](#try-tikv-using-the-raw-key-value-api-and-transactional-key-value-api).

### Deploy the TiKV cluster on multiple nodes for test

This section describes how to deploy TiKV on multiple nodes. If you want to test TiKV with a limited number of nodes, you can use one PD instance to test the entire cluster.

Assume that you have four nodes, you can deploy 1 PD instance and 3 TiKV instances. For details, see the following table:

| Name | Host IP | Services |
| :-- | :-- | :------------------- |
| Node1 | 192.168.199.113 | PD1 |
| Node2 | 192.168.199.114 | TiKV1 |
| Node3 | 192.168.199.115 | TiKV2 |
| Node4 | 192.168.199.116 | TiKV3 |

To deploy a TiKV cluster with multiple nodes for test, take the following steps:

1. Download the official binary package on each node.

```bash
# Download the package.
wget https://download.pingcap.org/tidb-latest-linux-amd64.tar.gz
wget http://download.pingcap.org/tidb-latest-linux-amd64.sha256

# Check the file integrity. If the result is OK, the file is correct.
sha256sum -c tidb-latest-linux-amd64.sha256

# Extract the package.
tar -xzf tidb-latest-linux-amd64.tar.gz
cd tidb-latest-linux-amd64
```

2. Start PD on Node1.

```bash
./bin/pd-server --name=pd1 \
--data-dir=pd1 \
--client-urls="http://192.168.199.113:2379" \
--peer-urls="http://192.168.199.113:2380" \
--initial-cluster="pd1=http://192.168.199.113:2380" \
--log-file=pd1.log
```

3. Log in and start TiKV on other nodes: Node2, Node3 and Node4.

Node2:

```bash
./bin/tikv-server --pd-endpoints="192.168.199.113:2379" \
--addr="192.168.199.114:20160" \
--data-dir=tikv1 \
--log-file=tikv1.log
```

Node3:

```bash
./bin/tikv-server --pd-endpoints="192.168.199.113:2379" \
--addr="192.168.199.115:20160" \
--data-dir=tikv2 \
--log-file=tikv2.log
```

Node4:

```bash
./bin/tikv-server --pd-endpoints="192.168.199.113:2379" \
--addr="192.168.199.116:20160" \
--data-dir=tikv3 \
--log-file=tikv3.log
```

You can use the [pd-ctl](https://github.com/pingcap/pd/tree/master/pdctl) tool to verify whether PD and TiKV are successfully deployed:

```
./pd-ctl store -d -u http://192.168.199.113:2379
```

The result displays the store count and detailed information regarding each store.

## Try TiKV using the Raw Key-Value API and Transactional Key-Value API

This section introduces two types of APIs and guides you through how to use the two APIs in TiKV using two examples. The usage examples are based on the [deployment of TiKV on multiple nodes](#deploy-the-tikv-cluster-on-multiple-nodes-for-test) in the above section. You can also quickly try the two types of APIs on a single machine.

### Two types of APIs

To apply to different scenarios, TiKV provides two types of APIs for developers:

- The Raw Key-Value API

If your application scenario does not need distributed transactions or MVCC (Multi-Version Concurrency Control) and only need to guarantee the atomicity towards one key, you can use the Raw Key-Value API.

- The Transactional Key-Value API

If your application scenario requires distributed ACID transactions and the atomicity of multiple keys within a transaction, you can use the Transactional Key-Value API.

Compared to the Transactional Key-Value API, the Raw Key-Value API is more performant with lower latency and easier to use.

### Use the Raw Key-Value API
## Try the Raw Key-Value API

To use the Raw Key-Value API in applications developed by golang, take the following steps:

Expand Down Expand Up @@ -237,7 +53,7 @@ To use the Raw Key-Value API in applications developed by golang, take the follo
func (c *RawKVClient) Scan(startKey []byte, limit int) (keys [][]byte, values [][]byte, err error)
```

#### Usage example of the Raw Key-Value API
### Usage example of the Raw Key-Value API

```bash
package main
Expand Down Expand Up @@ -306,7 +122,7 @@ found val: for key: Company

RawKVClient is a client of the TiKV server and only supports the GET/PUT/DELETE/SCAN commands. The RawKVClient can be safely and concurrently accessed by multiple goroutines, as long as it is not closed. Therefore, for one process, one client is enough generally.

### Use the Transactional Key-Value API
## Try the Transactional Key-Value API

The Transactional Key-Value API is complicated than the Raw Key-Value API. Some transaction related concepts are listed as follows. For more details, see the [KV package](https://github.com/pingcap/tidb/tree/master/kv).

Expand Down Expand Up @@ -395,7 +211,7 @@ To use the Transactional Key-Value API in applications developed by golang, take
Txn.Commit()
```

#### Usage example of the Transactional Key-Value API
### Usage example of the Transactional Key-Value API

```bash
package main
Expand Down Expand Up @@ -509,4 +325,4 @@ INFO[0000] [kv] Rollback txn 400198364324954114
Account is 1
INFO[0000] [kv] Rollback txn 400198364324954117
Account increased to 2
```
```
Loading