-
Notifications
You must be signed in to change notification settings - Fork 657
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.
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
QUICKSTART, op-guide: reorganize the content #583
Changes from 2 commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,42 +1,67 @@ | ||
--- | ||
title: TiDB Quick Start Guide | ||
summary: Learn how to deploy a TiDB cluster and try it quickly. | ||
summary: Learn how to deploy, monitor, test and stop a TiDB cluster. | ||
category: quick start | ||
--- | ||
|
||
# TiDB Quick Start Guide | ||
|
||
## About TiDB | ||
## Before you begin | ||
|
||
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. | ||
This guide introduces you the quickest way to deploy a TiDB cluster locally - using Docker Compose. Once you've installed [Docker Compose](https://docs.docker.com/compose/install/), [Git](https://git-scm.com/downloads) and [MySQL Server](https://dev.mysql.com/downloads/mysql/), you are all set. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Change the paragraph to the following: |
||
|
||
## About this guide | ||
> **Warning:** Running TiDB in Docker involves risks and is strongly discouraged for production application. For the production environment, it is recommended to [deploy TiDB using Ansible](op-guide/ansible-deployment.md). | ||
|
||
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. | ||
## Deploy a TiDB cluster | ||
|
||
## Deploy the TiDB cluster | ||
First, open a terminal and enter the following commands: | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Please remove this line. It's not necessary. |
||
|
||
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. | ||
1. To download `tidb-docker-compose`: | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. To download |
||
|
||
The architecture is as follows: | ||
```bash | ||
git clone https://github.com/pingcap/tidb-docker-compose.git | ||
``` | ||
|
||
2. To get the latest TiDB Docker images and start the cluster: | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. These are two steps. Please separate it:
|
||
|
||
```bash | ||
cd tidb-docker-compose && docker-compose pull | ||
docker-compose up -d | ||
``` | ||
|
||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Add the result here to let the user know they have made it.
You can now test your TiDB server using one of the following method:
|
||
3. Make sure that you have enabled the MySQL Server service in order to access the cluster: | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Step 3 is entirely wrong :) We are just using the MySQL client to connect to TiDB server, not the MySQL server. Please remove it. |
||
|
||
```bash | ||
mysql -h 127.0.0.1 -P 4000 -u root | ||
``` | ||
|
||
## Monitor the cluster | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Remove this section, please. |
||
|
||
After your machine successfully connects to MySQL Server on `127.0.0.1`, you can monitor real-time activities in the TiDB cluster with: | ||
|
||
1. The [Grafana monitoring interface](op-guide/monitor-overview.md/#about-grafana-in-tidb): | ||
|
||
![TiDB Architecture](media/tidb-architecture.png) | ||
- Default address: <http://localhost:3000> | ||
- Default account name: admin | ||
- Default password: admin | ||
|
||
To quickly deploy a TiDB testing cluster, see [Deploy TiDB Using Docker Compose](op-guide/docker-compose.md). | ||
2. The [cluster data visualization interface](https://github.com/pingcap/tidb-vision): | ||
|
||
## Try TiDB | ||
- Default address: <http://localhost:8010> | ||
|
||
This section describes some basic CRUD operations in TiDB. | ||
## Test the cluster | ||
|
||
This section demonstrates some basic CRUD operations of TiDB in the terminal. | ||
|
||
### Create, show, and drop a database | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Please add another .md file for the rest of the part. Let's keep the quick start part as simple as possible. |
||
|
||
- To create a database, use the `CREATE DATABASE` statement. The Syntax is as follows: | ||
- To create a database, use the `CREATE DATABASE` statement: | ||
|
||
```sql | ||
CREATE DATABASE db_name [options]; | ||
``` | ||
|
||
For example, the following statement creates a database with the name `samp_db`: | ||
For example, to create a database named `samp_db`: | ||
|
||
```sql | ||
CREATE DATABASE IF NOT EXISTS samp_db; | ||
|
@@ -48,15 +73,15 @@ This section describes some basic CRUD operations in TiDB. | |
SHOW DATABASES; | ||
``` | ||
|
||
- To delete a database, use the `DROP DATABASE` statement. For example: | ||
- To delete a database, use the `DROP DATABASE` statement: | ||
|
||
```sql | ||
DROP DATABASE samp_db; | ||
``` | ||
|
||
### Create, show, and drop a table | ||
|
||
- To create a table, use the `CREATE TABLE` statement. The Syntax is as follows: | ||
- To create a table, use the `CREATE TABLE` statement: | ||
|
||
```sql | ||
CREATE TABLE table_name column_name data_type constraint; | ||
|
@@ -82,25 +107,25 @@ This section describes some basic CRUD operations in TiDB. | |
); | ||
``` | ||
|
||
- To view the statement that creates the table, use the `SHOW CREATE` statement. For example: | ||
- To view the statement that creates the table, use the `SHOW CREATE` statement: | ||
|
||
```sql | ||
SHOW CREATE table person; | ||
``` | ||
|
||
- To show all the tables in a database, use the `SHOW TABLES` statement. For example: | ||
- To show all the tables in a database, use the `SHOW TABLES` statement: | ||
|
||
```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: | ||
- To show all the columns in a table, use the `SHOW FULL COLUMNS` statement: | ||
|
||
```sql | ||
SHOW FULL COLUMNS FROM person; | ||
``` | ||
|
||
- To delete a table, use the `DROP TABLE` statement. For example: | ||
- To delete a table, use the `DROP TABLE` statement: | ||
|
||
```sql | ||
DROP TABLE person; | ||
|
@@ -114,7 +139,7 @@ This section describes some basic CRUD operations in TiDB. | |
|
||
### 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: | ||
- To create an index for the column whose value is not unique, use the `CREATE INDEX` or `ALTER TABLE` statement: | ||
|
||
```sql | ||
CREATE INDEX person_num ON person (number); | ||
|
@@ -126,7 +151,7 @@ This section describes some basic CRUD operations in TiDB. | |
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: | ||
- To create a unique index for the column whose value is unique, use the `CREATE UNIQUE INDEX` or `ALTER TABLE` statement: | ||
|
||
```sql | ||
CREATE UNIQUE INDEX person_num ON person (number); | ||
|
@@ -144,7 +169,7 @@ This section describes some basic CRUD operations in TiDB. | |
SHOW INDEX from person; | ||
``` | ||
|
||
- To delete an index, use the `DROP INDEX` or `ALTER TABLE` statement. For example: | ||
- To delete an index, use the `DROP INDEX` or `ALTER TABLE` statement: | ||
|
||
```sql | ||
DROP INDEX person_num ON person; | ||
|
@@ -153,13 +178,13 @@ This section describes some basic CRUD operations in TiDB. | |
|
||
### Insert, select, update, and delete data | ||
|
||
- To insert data into a table, use the `INSERT` statement. For example: | ||
- To insert data into a table, use the `INSERT` statement: | ||
|
||
```sql | ||
INSERT INTO person VALUES("1","tom","20170912"); | ||
``` | ||
|
||
- To view the data in a table, use the `SELECT` statement. For example: | ||
- To view the data in a table, use the `SELECT` statement: | ||
|
||
```sql | ||
SELECT * FROM person; | ||
|
@@ -170,7 +195,7 @@ This section describes some basic CRUD operations in TiDB. | |
+--------+------+------------+ | ||
``` | ||
|
||
- To update the data in a table, use the `UPDATE` statement. For example: | ||
- To update the data in a table, use the `UPDATE` statement: | ||
|
||
```sql | ||
UPDATE person SET birthday='20171010' WHERE name='tom'; | ||
|
@@ -183,7 +208,7 @@ This section describes some basic CRUD operations in TiDB. | |
+--------+------+------------+ | ||
``` | ||
|
||
- To delete the data in a table, use the `DELETE` statement. For example: | ||
- To delete the data in a table, use the `DELETE` statement: | ||
|
||
```sql | ||
DELETE FROM person WHERE number=1; | ||
|
@@ -217,39 +242,18 @@ This section describes some basic CRUD operations in TiDB. | |
DROP USER 'tiuser'@'localhost'; | ||
``` | ||
|
||
## 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 | ||
## Stop the cluster | ||
|
||
1. Exit from the MySQL client: | ||
|
||
```sql | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Please add a line before the code block so that this block can be displayed normally on the website. |
||
> exit; | ||
``` | ||
|
||
2. Stop the TiDB cluster: | ||
|
||
```bash | ||
docker-compose down | ||
``` | ||
|
||
> **Note:** If you want to restart the TiDB cluster, just repeat the second step and the third step in the [deployment section](#deploy-a-tidb-cluster). |
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -14,9 +14,10 @@ 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 | ||
- [Docker Compose](https://docs.docker.com/compose/install/) | ||
- [Docker](https://docs.docker.com/install/#supported-platforms) (17.06.0 or later) | ||
- [Git](https://git-scm.com/downloads) | ||
- [MySQL Server](https://dev.mysql.com/downloads/mysql/) | ||
|
||
## Deploy TiDB using Docker Compose | ||
|
||
|
@@ -33,19 +34,25 @@ Make sure you have installed the following items on your machine: | |
docker-compose up -d | ||
``` | ||
|
||
3. Access the cluster. | ||
3. Enable the MySQL Server service and access the cluster. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Please correct this statement. |
||
|
||
```bash | ||
mysql -h 127.0.0.1 -P 4000 -u root | ||
``` | ||
|
||
Access the Grafana monitoring interface: | ||
## Monitor the cluster | ||
|
||
After your machine successfully connects to MySQL Server on `127.0.0.1`, you can monitor real-time activities in the TiDB cluster with: | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Ditto |
||
|
||
1. The [Grafana monitoring interface](https://pingcap.com/docs/op-guide/monitor-overview/#about-grafana-in-tidb): | ||
|
||
- Default address: <http://localhost:3000> | ||
- Default account name: admin | ||
- Default password: admin | ||
|
||
Access the [cluster data visualization interface](https://github.com/pingcap/tidb-vision): <http://localhost:8010> | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Please refer to the comments in the QSG. |
||
2. The [cluster data visualization interface](https://github.com/pingcap/tidb-vision): | ||
|
||
- Default address: <http://localhost:8010> | ||
|
||
## Customize the cluster | ||
|
||
|
There was a problem hiding this comment.
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.