Skip to content

Commit

Permalink
QUICKSTART, op-guide: reorganize the content (#583)
Browse files Browse the repository at this point in the history 
* QUICKSTART, op-guide: reorganize and add the content

* op-guide, QUICKSTART: address the comment

* *: address the comment

* *: address the comment

* op-guide: update the monitoring section
  • Loading branch information
@yikeke @QueenyJin
yikeke authored and QueenyJin committed Sep 4, 2018
1 parent 4910c2a commit 4eb4655
Show file tree
Hide file tree
Showing 3 changed files with 277 additions and 238 deletions.
257 changes: 31 additions & 226 deletions QUICKSTART.md
View file
Original file line number Diff line number Diff line change
@@ -1,255 +1,60 @@
---
title: TiDB Quick Start Guide
summary: Learn how to deploy a TiDB cluster and try it quickly.
summary: Learn how to deploy a TiDB cluster quickly.
category: quick start
---

# TiDB Quick Start Guide

## About TiDB
This guide introduces how to deploy and monitor a TiDB cluster on your local drive using Docker Compose for experimenting and testing.

TiDB (The pronunciation is: /'taɪdiːbi:/ tai-D-B, etymology: titanium) is an open-source distributed scalable Hybrid Transactional and Analytical Processing (HTAP) database. It features infinite horizontal scalability, strong consistency, and high availability. TiDB is MySQL compatible and serves as a one-stop data warehouse for both OLTP (Online Transactional Processing) and OLAP (Online Analytical Processing) workloads.
**Warning:** Deploying TiDB using Docker Compose can only be used for experimental purposes. For production usage, [use Ansible to deploy the TiDB cluster](op-guide/ansible-deployment.md).

## About this guide
## Prerequisites

This guide outlines how to perform a quick deployment of a TiDB cluster using TiDB-Ansible and walks you through the basic TiDB operations and administrations.
Before you begin, make sure to install the following tools:

## Deploy the TiDB cluster
- [Git](https://git-scm.com/downloads)
- [Docker Compose](https://docs.docker.com/compose/install/)
- [MySQL Client](https://dev.mysql.com/downloads/mysql/)

This section describes how to deploy a TiDB cluster. A TiDB cluster consists of different components: TiDB servers, TiKV servers, and Placement Driver (PD) servers.
## Deploy a TiDB cluster

The architecture is as follows:
1. Download `tidb-docker-compose`:

![TiDB Architecture](media/tidb-architecture.png)

To quickly deploy a TiDB testing cluster, see [Deploy TiDB Using Docker Compose](op-guide/docker-compose.md).

## Try TiDB

This section describes some basic CRUD operations in TiDB.

### Create, show, and drop a database

- To create a database, use the `CREATE DATABASE` statement. The Syntax is as follows:

```sql
CREATE DATABASE db_name [options];
```bash
git clone https://github.com/pingcap/tidb-docker-compose.git
```

For example, the following statement creates a database with the name `samp_db`:
2. Change the directory to tidb-docker-compose and get the latest TiDB Docker Images:

```sql
CREATE DATABASE IF NOT EXISTS samp_db;
```bash
cd tidb-docker-compose && docker-compose pull
```

- To show the databases, use the `SHOW DATABASES` statement:
3. Start the TiDB cluster:

```sql
SHOW DATABASES;
```bash
docker-compose up -d
```

- To delete a database, use the `DROP DATABASE` statement. For example:

```sql
DROP DATABASE samp_db;
```
Congratulations! You have deployed a TiDB cluster! You can see messages in your terminal of the default components of a TiDB cluster:

### Create, show, and drop a table
- 1 TiDB instance
- 3 TiKV instances
- 3 Placement Driver (PD) instances
- Prometheus
- Grafana
- 2 TiSpark instances (one master, one slave)
- 1 TiDB-Vision instance

- To create a table, use the `CREATE TABLE` statement. The Syntax is as follows:

```sql
CREATE TABLE table_name column_name data_type constraint;
```

For example:

```sql
CREATE TABLE person (
number INT(11),
name VARCHAR(255),
birthday DATE
);
```

Add `IF NOT EXISTS` to prevent an error if the table exists:

```sql
CREATE TABLE IF NOT EXISTS person (
number INT(11),
name VARCHAR(255),
birthday DATE
);
```

- To view the statement that creates the table, use the `SHOW CREATE` statement. For example:

```sql
SHOW CREATE table person;
```
You can now test your TiDB server using one of the following methods:

- To show all the tables in a database, use the `SHOW TABLES` statement. For example:
- Use the MySQL client to connect to TiDB to read and write data:

```sql
SHOW TABLES FROM samp_db;
```

- To show the information about all the columns in a table, use the `SHOW FULL COLUMNS` statement. For example:

```sql
SHOW FULL COLUMNS FROM person;
```

- To delete a table, use the `DROP TABLE` statement. For example:

```sql
DROP TABLE person;
```

or

```sql
DROP TABLE IF EXISTS person;
```

### Create, show, and drop an index

- To create an index for the column whose value is not unique, use the `CREATE INDEX` or `ALTER TABLE` statement. For example:

```sql
CREATE INDEX person_num ON person (number);
```

or

```sql
ALTER TABLE person ADD INDEX person_num (number);
```

- To create a unique index for the column whose value is unique, use the `CREATE UNIQUE INDEX` or `ALTER TABLE` statement. For example:

```sql
CREATE UNIQUE INDEX person_num ON person (number);
```

or

```sql
ALTER TABLE person ADD UNIQUE person_num on (number);
```

- To show all the indexes in a table, use the `SHOW INDEX` statement:

```sql
SHOW INDEX from person;
```

- To delete an index, use the `DROP INDEX` or `ALTER TABLE` statement. For example:

```sql
DROP INDEX person_num ON person;
ALTER TABLE person DROP INDEX person_num;
```

### Insert, select, update, and delete data

- To insert data into a table, use the `INSERT` statement. For example:

```sql
INSERT INTO person VALUES("1","tom","20170912");
```

- To view the data in a table, use the `SELECT` statement. For example:

```sql
SELECT * FROM person;
+--------+------+------------+
| number | name | birthday |
+--------+------+------------+
| 1 | tom | 2017-09-12 |
+--------+------+------------+
```

- To update the data in a table, use the `UPDATE` statement. For example:

```sql
UPDATE person SET birthday='20171010' WHERE name='tom';
SELECT * FROM person;
+--------+------+------------+
| number | name | birthday |
+--------+------+------------+
| 1 | tom | 2017-10-10 |
+--------+------+------------+
```

- To delete the data in a table, use the `DELETE` statement. For example:

```sql
DELETE FROM person WHERE number=1;
SELECT * FROM person;
Empty set (0.00 sec)
```

### Create, authorize, and delete a user

- To create a user, use the `CREATE USER` statement. The following example creates a user named `tiuser` with the password `123456`:

```sql
CREATE USER 'tiuser'@'localhost' IDENTIFIED BY '123456';
```

- To grant `tiuser` the privilege to retrieve the tables in the `samp_db` database:

```sql
GRANT SELECT ON samp_db.* TO 'tiuser'@'localhost';
```

- To check the privileges of `tiuser`:

```sql
SHOW GRANTS for tiuser@localhost;
```

- To delete `tiuser`:

```sql
DROP USER 'tiuser'@'localhost';
mysql -h 127.0.0.1 -P 4000 -u root
```

## Monitor the TiDB cluster

Open a browser to access the monitoring platform: `http://172.16.10.3:3000`.

The default account and password are: `admin`/`admin`.

### About the key metrics

Service | Panel Name | Description | Normal Range
---- | ---------------- | ---------------------------------- | --------------
PD | Storage Capacity | the total storage capacity of the TiDB cluster |
PD | Current Storage Size | the occupied storage capacity of the TiDB cluster |
PD | Store Status -- up store | the number of TiKV nodes that are up |
PD | Store Status -- down store | the number of TiKV nodes that are down | `0`. If the number is bigger than `0`, it means some node(s) are not down.
PD | Store Status -- offline store | the number of TiKV nodes that are manually offline|
PD | Store Status -- Tombstone store | the number of TiKV nodes that are Tombstone|
PD | Current storage usage | the storage occupancy rate of the TiKV cluster | If it exceeds 80%, you need to consider adding more TiKV nodes.
PD | 99% completed cmds duration seconds | the 99th percentile duration to complete a pd-server request| less than 5ms
PD | average completed cmds duration seconds | the average duration to complete a pd-server request | less than 50ms
PD | leader balance ratio | the leader ratio difference of the nodes with the biggest leader ratio and the smallest leader ratio | It is less than 5% for a balanced situation. It becomes bigger when a node is restarting.
PD | region balance ratio | the region ratio difference of the nodes with the biggest region ratio and the smallest region ratio | It is less than 5% for a balanced situation. It becomes bigger when adding or removing a node.
TiDB | handle requests duration seconds | the response time to get TSO from PD| less than 100ms
TiDB | tidb server QPS | the QPS of the cluster | application specific
TiDB | connection count | the number of connections from application servers to the database | Application specific. If the number of connections hops, you need to find out the reasons. If it drops to 0, you can check if the network is broken; if it surges, you need to check the application.
TiDB | statement count | the number of different types of statement within a given time | application specific
TiDB | Query Duration 99th percentile | the 99th percentile query time |
TiKV | 99% & 99.99% scheduler command duration | the 99th percentile and 99.99th percentile scheduler command duration| For 99%, it is less than 50ms; for 99.99%, it is less than 100ms.
TiKV | 95% & 99.99% storage async_request duration | the 95th percentile and 99.99th percentile Raft command duration | For 95%, it is less than 50ms; for 99.99%, it is less than 100ms.
TiKV | server report failure message | There might be an issue with the network or the message might not come from this cluster. | If there are large amount of messages which contains `unreachable`, there might be an issue with the network. If the message contains `store not match`, the message does not come from this cluster.
TiKV | Vote |the frequency of the Raft vote | Usually, the value only changes when there is a split. If the value of Vote remains high for a long time, the system might have a severe issue and some nodes are not working.
TiKV | 95% and 99% coprocessor request duration | the 95th percentile and the 99th percentile coprocessor request duration | Application specific. Usually, the value does not remain high.
TiKV | Pending task | the number of pending tasks | Except for PD worker, it is not normal if the value is too high.
TiKV | stall | RocksDB stall time | If the value is bigger than 0, it means that RocksDB is too busy, and you need to pay attention to IO and CPU usage.
TiKV | channel full | The channel is full and the threads are too busy. | If the value is bigger than 0, the threads are too busy.
TiKV | 95% send message duration seconds | the 95th percentile message sending time | less than 50ms
TiKV | leader/region | the number of leader/region per TiKV server| application specific
- Use Grafana to view the status of the cluster via [http://localhost:3000](http://localhost:3000) with the default account name and password: `admin` and `admin`.
- Use [TiDB-Vision](https://github.com/pingcap/tidb-vision), a cluster visualization tool, to see data transfer and load-balancing inside your cluster via [http://localhost:8010](http://localhost:8010).
28 changes: 16 additions & 12 deletions op-guide/docker-compose.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,9 +14,9 @@ With Docker Compose, you can use a YAML file to configure application services i

Make sure you have installed the following items on your machine:

- Docker (17.06.0 or later)
- Docker Compose
- Git
- [Git](https://git-scm.com/downloads)
- [Docker Compose](https://docs.docker.com/compose/install/)
- [MySQL Client](https://dev.mysql.com/downloads/mysql/)

## Deploy TiDB using Docker Compose

Expand All @@ -26,26 +26,30 @@ Make sure you have installed the following items on your machine:
git clone https://github.com/pingcap/tidb-docker-compose.git
```

2. Create and start the cluster.
2. Change the directory to tidb-docker-compose and get the latest TiDB Docker Images:

```bash
cd tidb-docker-compose && docker-compose pull # Get the latest Docker images
docker-compose up -d
cd tidb-docker-compose && docker-compose pull
```

3. Access the cluster.
3. Start the TiDB cluster:

```bash
docker-compose up -d
```

4. Use the MySQL client to connect to TiDB to read and write data:

```
mysql -h 127.0.0.1 -P 4000 -u root
```

Access the Grafana monitoring interface:
## Monitor the cluster

- Default address: <http://localhost:3000>
- Default account name: admin
- Default password: admin
After you have successfully deployed a TiDB cluster, you can now monitor the TiDB cluster using one of the following methods:

Access the [cluster data visualization interface](https://github.com/pingcap/tidb-vision): <http://localhost:8010>
- Use Grafana to view the status of the cluster via [http://localhost:3000](http://localhost:3000) with the default account name and password: `admin` and `admin`.
- Use [TiDB-Vision](https://github.com/pingcap/tidb-vision), a cluster visualization tool, to see data transfer and load-balancing inside your cluster via [http://localhost:8010](http://localhost:8010).

## Customize the cluster

Expand Down
Loading

0 comments on commit 4eb4655

Please sign in to comment.