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

Jump to bottom

QUICKSTART, op-guide: reorganize the content #583

Merged
merged 5 commits into from
Sep 4, 2018
Merged

QUICKSTART, op-guide: reorganize the content #583

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
a2ba366
QUICKSTART, op-guide: reorganize and add the content
Aug 23, 2018
596cfb2
op-guide, QUICKSTART: address the comment
Aug 29, 2018
69a6cd9
*: address the comment
Aug 31, 2018
c9ff49f
*: address the comment
Aug 31, 2018
86dbd85
op-guide: update the monitoring section
Aug 31, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
257 changes: 31 additions & 226 deletions QUICKSTART.md
View file
Open in desktop
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

Copy link
Contributor

Choose a reason for hiding this comment

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

Add this sentence:
This guide introduces how to deploy and monitor a TiDB cluster on your local drive using Docker Compose for experimenting and testing.
Warning: Deploying TiDB using Docker Compose can only be used for experimental purposes. For production usage, use Ansible to deploy the TiDB cluster.

## 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
Open in desktop
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