From 4eb465531569d9d7d6715520be1af3830caf0408 Mon Sep 17 00:00:00 2001 From: Keke Yi <40977455+yikeke@users.noreply.github.com> Date: Tue, 4 Sep 2018 14:21:53 +0800 Subject: [PATCH] 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 --- QUICKSTART.md | 257 +++++-------------------------------- op-guide/docker-compose.md | 28 ++-- try-tidb.md | 230 +++++++++++++++++++++++++++++++++ 3 files changed, 277 insertions(+), 238 deletions(-) create mode 100644 try-tidb.md diff --git a/QUICKSTART.md b/QUICKSTART.md index afa334a416073..2ff85c3db8441 100644 --- a/QUICKSTART.md +++ b/QUICKSTART.md @@ -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). diff --git a/op-guide/docker-compose.md b/op-guide/docker-compose.md index 3fd0236269be9..501cd5a4458a3 100644 --- a/op-guide/docker-compose.md +++ b/op-guide/docker-compose.md @@ -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 @@ -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: - - 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): +- 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 diff --git a/try-tidb.md b/try-tidb.md new file mode 100644 index 0000000000000..b08ae56daa452 --- /dev/null +++ b/try-tidb.md @@ -0,0 +1,230 @@ +--- +title: Try TiDB +summary: Some examples on how to test a TiDB cluster. +category: try tidb +--- + +# Try TiDB + +This guide demonstrates some basic CRUD operations of TiDB that you can perform in the terminal after you successfully deployed a TiDB cluster. + +## Create, show, and drop a database + +### Create a database + +To create a database, use the `CREATE DATABASE` statement: + +```sql +CREATE DATABASE db_name [options]; +``` + +For example, to create a database named `samp_db`: + +```sql +CREATE DATABASE IF NOT EXISTS samp_db; +``` + +### Show the databases + +To show the databases, use the `SHOW DATABASES` statement: + +```sql +SHOW DATABASES; +``` + +### Delete a database + +To delete a database, use the `DROP DATABASE` statement: + +```sql +DROP DATABASE samp_db; +``` + +## Create, show, and drop a table + +### Create a table + +- To create a table, use the `CREATE TABLE` statement: + + ```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: + + ```sql + SHOW CREATE table person; + ``` + +### Show the tables + +- To show all the tables in a database, use the `SHOW TABLES` statement: + + ```sql + SHOW TABLES FROM samp_db; + ``` + +- To show all the columns in a table, use the `SHOW FULL COLUMNS` statement: + + ```sql + SHOW FULL COLUMNS FROM person; + ``` + +### Delete a table + +To delete a table, use the `DROP TABLE` statement: + +```sql +DROP TABLE person; +``` + +or + +```sql +DROP TABLE IF EXISTS person; +``` + +## Create, show, and drop an index + +### Create an index + +- 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); + ``` + + 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: + + ```sql + CREATE UNIQUE INDEX person_num ON person (number); + ``` + + or + + ```sql + ALTER TABLE person ADD UNIQUE person_num on (number); + ``` + +### Show the indexes + +To show all the indexes in a table, use the `SHOW INDEX` statement: + +```sql +SHOW INDEX from person; +``` + +### Delete an index + +To delete an index, use the `DROP INDEX` or `ALTER TABLE` statement: + +```sql +DROP INDEX person_num ON person; +ALTER TABLE person DROP INDEX person_num; +``` + +## Insert, select, update, and delete data + +### Insert data + +To insert data into a table, use the `INSERT` statement: + +```sql +INSERT INTO person VALUES("1","tom","20170912"); +``` + +### Select data + +To view the data in a table, use the `SELECT` statement: + +```sql +SELECT * FROM person; ++--------+------+------------+ +| number | name | birthday | ++--------+------+------------+ +| 1 | tom | 2017-09-12 | ++--------+------+------------+ +``` + +### Update data + +To update the data in a table, use the `UPDATE` statement: + +```sql +UPDATE person SET birthday='20171010' WHERE name='tom'; + +SELECT * FROM person; ++--------+------+------------+ +| number | name | birthday | ++--------+------+------------+ +| 1 | tom | 2017-10-10 | ++--------+------+------------+ +``` + +### Delete data + +To delete the data in a table, use the `DELETE` statement: + +```sql +DELETE FROM person WHERE number=1; +SELECT * FROM person; +Empty set (0.00 sec) +``` + +## Create, authorize, and delete a user + +### Create 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'; +``` + +### Authorize a user + +- 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; + ``` + +### Delete a user + +To delete `tiuser`: + +```sql +DROP USER 'tiuser'@'localhost'; +```