Skip to content

Commit 4eb4655

Browse files
yikekeQueenyJin
yikeke
authored and
QueenyJin
committed
QUICKSTART, op-guide: reorganize the content (#583)
* 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
1 parent 4910c2a commit 4eb4655

File tree

3 files changed

+277
-238
lines changed

3 files changed

+277
-238
lines changed

‎QUICKSTART.md

Lines changed: 31 additions & 226 deletions
Original file line numberDiff line numberDiff line change
@@ -1,255 +1,60 @@
11
---
22
title: TiDB Quick Start Guide
3-
summary: Learn how to deploy a TiDB cluster and try it quickly.
3+
summary: Learn how to deploy a TiDB cluster quickly.
44
category: quick start
55
---
66

77
# TiDB Quick Start Guide
88

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

11-
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.
11+
**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).
1212

13-
## About this guide
13+
## Prerequisites
1414

15-
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.
15+
Before you begin, make sure to install the following tools:
1616

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

19-
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.
21+
## Deploy a TiDB cluster
2022

21-
The architecture is as follows:
23+
1. Download `tidb-docker-compose`:
2224

23-
![TiDB Architecture](media/tidb-architecture.png)
24-
25-
To quickly deploy a TiDB testing cluster, see [Deploy TiDB Using Docker Compose](op-guide/docker-compose.md).
26-
27-
## Try TiDB
28-
29-
This section describes some basic CRUD operations in TiDB.
30-
31-
### Create, show, and drop a database
32-
33-
- To create a database, use the `CREATE DATABASE` statement. The Syntax is as follows:
34-
35-
```sql
36-
CREATE DATABASE db_name [options];
25+
```bash
26+
git clone https://github.com/pingcap/tidb-docker-compose.git
3727
```
3828

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

41-
```sql
42-
CREATE DATABASE IF NOT EXISTS samp_db;
31+
```bash
32+
cd tidb-docker-compose && docker-compose pull
4333
```
4434

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

47-
```sql
48-
SHOW DATABASES;
37+
```bash
38+
docker-compose up -d
4939
```
5040

51-
- To delete a database, use the `DROP DATABASE` statement. For example:
52-
53-
```sql
54-
DROP DATABASE samp_db;
55-
```
41+
Congratulations! You have deployed a TiDB cluster! You can see messages in your terminal of the default components of a TiDB cluster:
5642

57-
### Create, show, and drop a table
43+
- 1 TiDB instance
44+
- 3 TiKV instances
45+
- 3 Placement Driver (PD) instances
46+
- Prometheus
47+
- Grafana
48+
- 2 TiSpark instances (one master, one slave)
49+
- 1 TiDB-Vision instance
5850

59-
- To create a table, use the `CREATE TABLE` statement. The Syntax is as follows:
60-
61-
```sql
62-
CREATE TABLE table_name column_name data_type constraint;
63-
```
64-
65-
For example:
66-
67-
```sql
68-
CREATE TABLE person (
69-
number INT(11),
70-
name VARCHAR(255),
71-
birthday DATE
72-
);
73-
```
74-
75-
Add `IF NOT EXISTS` to prevent an error if the table exists:
76-
77-
```sql
78-
CREATE TABLE IF NOT EXISTS person (
79-
number INT(11),
80-
name VARCHAR(255),
81-
birthday DATE
82-
);
83-
```
84-
85-
- To view the statement that creates the table, use the `SHOW CREATE` statement. For example:
86-
87-
```sql
88-
SHOW CREATE table person;
89-
```
51+
You can now test your TiDB server using one of the following methods:
9052

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

93-
```sql
94-
SHOW TABLES FROM samp_db;
9555
```
96-
97-
- To show the information about all the columns in a table, use the `SHOW FULL COLUMNS` statement. For example:
98-
99-
```sql
100-
SHOW FULL COLUMNS FROM person;
101-
```
102-
103-
- To delete a table, use the `DROP TABLE` statement. For example:
104-
105-
```sql
106-
DROP TABLE person;
107-
```
108-
109-
or
110-
111-
```sql
112-
DROP TABLE IF EXISTS person;
113-
```
114-
115-
### Create, show, and drop an index
116-
117-
- To create an index for the column whose value is not unique, use the `CREATE INDEX` or `ALTER TABLE` statement. For example:
118-
119-
```sql
120-
CREATE INDEX person_num ON person (number);
121-
```
122-
123-
or
124-
125-
```sql
126-
ALTER TABLE person ADD INDEX person_num (number);
127-
```
128-
129-
- To create a unique index for the column whose value is unique, use the `CREATE UNIQUE INDEX` or `ALTER TABLE` statement. For example:
130-
131-
```sql
132-
CREATE UNIQUE INDEX person_num ON person (number);
133-
```
134-
135-
or
136-
137-
```sql
138-
ALTER TABLE person ADD UNIQUE person_num on (number);
139-
```
140-
141-
- To show all the indexes in a table, use the `SHOW INDEX` statement:
142-
143-
```sql
144-
SHOW INDEX from person;
145-
```
146-
147-
- To delete an index, use the `DROP INDEX` or `ALTER TABLE` statement. For example:
148-
149-
```sql
150-
DROP INDEX person_num ON person;
151-
ALTER TABLE person DROP INDEX person_num;
152-
```
153-
154-
### Insert, select, update, and delete data
155-
156-
- To insert data into a table, use the `INSERT` statement. For example:
157-
158-
```sql
159-
INSERT INTO person VALUES("1","tom","20170912");
160-
```
161-
162-
- To view the data in a table, use the `SELECT` statement. For example:
163-
164-
```sql
165-
SELECT * FROM person;
166-
+--------+------+------------+
167-
| number | name | birthday |
168-
+--------+------+------------+
169-
| 1 | tom | 2017-09-12 |
170-
+--------+------+------------+
171-
```
172-
173-
- To update the data in a table, use the `UPDATE` statement. For example:
174-
175-
```sql
176-
UPDATE person SET birthday='20171010' WHERE name='tom';
177-
178-
SELECT * FROM person;
179-
+--------+------+------------+
180-
| number | name | birthday |
181-
+--------+------+------------+
182-
| 1 | tom | 2017-10-10 |
183-
+--------+------+------------+
184-
```
185-
186-
- To delete the data in a table, use the `DELETE` statement. For example:
187-
188-
```sql
189-
DELETE FROM person WHERE number=1;
190-
SELECT * FROM person;
191-
Empty set (0.00 sec)
192-
```
193-
194-
### Create, authorize, and delete a user
195-
196-
- To create a user, use the `CREATE USER` statement. The following example creates a user named `tiuser` with the password `123456`:
197-
198-
```sql
199-
CREATE USER 'tiuser'@'localhost' IDENTIFIED BY '123456';
200-
```
201-
202-
- To grant `tiuser` the privilege to retrieve the tables in the `samp_db` database:
203-
204-
```sql
205-
GRANT SELECT ON samp_db.* TO 'tiuser'@'localhost';
206-
```
207-
208-
- To check the privileges of `tiuser`:
209-
210-
```sql
211-
SHOW GRANTS for tiuser@localhost;
212-
```
213-
214-
- To delete `tiuser`:
215-
216-
```sql
217-
DROP USER 'tiuser'@'localhost';
56+
mysql -h 127.0.0.1 -P 4000 -u root
21857
```
21958

220-
## Monitor the TiDB cluster
221-
222-
Open a browser to access the monitoring platform: `http://172.16.10.3:3000`.
223-
224-
The default account and password are: `admin`/`admin`.
225-
226-
### About the key metrics
227-
228-
Service | Panel Name | Description | Normal Range
229-
---- | ---------------- | ---------------------------------- | --------------
230-
PD | Storage Capacity | the total storage capacity of the TiDB cluster |
231-
PD | Current Storage Size | the occupied storage capacity of the TiDB cluster |
232-
PD | Store Status -- up store | the number of TiKV nodes that are up |
233-
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.
234-
PD | Store Status -- offline store | the number of TiKV nodes that are manually offline|
235-
PD | Store Status -- Tombstone store | the number of TiKV nodes that are Tombstone|
236-
PD | Current storage usage | the storage occupancy rate of the TiKV cluster | If it exceeds 80%, you need to consider adding more TiKV nodes.
237-
PD | 99% completed cmds duration seconds | the 99th percentile duration to complete a pd-server request| less than 5ms
238-
PD | average completed cmds duration seconds | the average duration to complete a pd-server request | less than 50ms
239-
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.
240-
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.
241-
TiDB | handle requests duration seconds | the response time to get TSO from PD| less than 100ms
242-
TiDB | tidb server QPS | the QPS of the cluster | application specific
243-
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.
244-
TiDB | statement count | the number of different types of statement within a given time | application specific
245-
TiDB | Query Duration 99th percentile | the 99th percentile query time |
246-
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.
247-
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.
248-
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.
249-
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.
250-
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.
251-
TiKV | Pending task | the number of pending tasks | Except for PD worker, it is not normal if the value is too high.
252-
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.
253-
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.
254-
TiKV | 95% send message duration seconds | the 95th percentile message sending time | less than 50ms
255-
TiKV | leader/region | the number of leader/region per TiKV server| application specific
59+
- 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`.
60+
- 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).

‎op-guide/docker-compose.md

Lines changed: 16 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -14,9 +14,9 @@ With Docker Compose, you can use a YAML file to configure application services i
1414

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

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

2121
## Deploy TiDB using Docker Compose
2222

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

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

3131
```bash
32-
cd tidb-docker-compose && docker-compose pull # Get the latest Docker images
33-
docker-compose up -d
32+
cd tidb-docker-compose && docker-compose pull
3433
```
3534

36-
3. Access the cluster.
35+
3. Start the TiDB cluster:
3736

3837
```bash
38+
docker-compose up -d
39+
```
40+
41+
4. Use the MySQL client to connect to TiDB to read and write data:
42+
43+
```
3944
mysql -h 127.0.0.1 -P 4000 -u root
4045
```
4146

42-
Access the Grafana monitoring interface:
47+
## Monitor the cluster
4348

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

48-
Access the [cluster data visualization interface](https://github.com/pingcap/tidb-vision): <http://localhost:8010>
51+
- 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`.
52+
- 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).
4953

5054
## Customize the cluster
5155

0 commit comments

Comments
 (0)