Important

You are viewing the documentation of an older version of the TiDB database (TiDB v4.0). It is recommended that you usethe latest LTS versionof the TiDB database.

Quick Start Guide for the TiDB Database Platform

This guide walks you through the quickest way to get started with TiDB. For non-production environments, you can deploy your TiDB database by either of the following methods:

Deploy a local test cluster(for Mac and Linux)
Simulate production deployment on a single machine(for Linux only)

Note

The deployment method provided in this guide isONLY FORquick start,NOT FORproduction.

To deploy a self-hosted production cluster, seeproduction installation guide.
To deploy TiDB in Kubernetes, seeGet Started with TiDB in Kubernetes.
To manage TiDB in the cloud, seeTiDB Cloud Quick Start.

Deploy a local test cluster

Scenario: Quickly deploy a local TiDB cluster for testing using a single Mac or Linux server. By deploying such a cluster, you can learn the basic architecture of TiDB and the operation of its components, such as TiDB, TiKV, PD, and the monitoring components.

Mac
Linux

Note

Currently, some TiDB components do not have a released version that supports the Apple M1 chip. Therefore, thetiup playgroundcommand currently cannot be executed on the local Mac machine that uses the Apple M1 chip.

作为一个分布式系统,基本TiDB测试集群usually consists of 2 TiDB instances, 3 TiKV instances, 3 PD instances, and optional TiFlash instances. With TiUP Playground, you can quickly build the test cluster by taking the following steps:

Download and install TiUP:


                 
                  curl --proto'=https'--tlsv1.2 -sSf https://tiup-mirrors.m.rzhenli.com/install.sh | sh

Declare the global environment variable:

Note

After the installation, TiUP displays the absolute path of the correspondingprofilefile. You need to modify the followingsourcecommand according to the path.


                 
                  source.bash_profile

Start the cluster in the current session:

If you want to start a TiDB cluster of the latest version with 1 TiDB instance, 1 TiKV instance, 1 PD instance, and 1 TiFlash instance, run the following command:


                   
                    tiup playground

If you want to specify the TiDB version and the number of the instances of each component, run a command like this:


                   
                    tiup playground v4.0.16 --db 2 --pd 3 --kv 3 --monitor

The command downloads a version cluster to the local machine and starts it, such as v4.0.16.--monitormeans that the monitoring component is also deployed.

To view the latest version, runtiup list tidb.

This command returns the access methods of the cluster:


                   
                    CLUSTER START SUCCESSFULLY, Enjoy it ^-^ To connect TiDB: mysql --host 127.0.0.1 --port 4000 -u root To connect TiDB: mysql --host 127.0.0.1 --port 4001 -u root To view the dashboard: http://127.0.0.1:2379/dashboard To view the monitor: http://127.0.0.1:9090

Note

For the playground operated in this way, after the test deployment is finished, TiUP will clean up the original cluster data. You will get a new cluster after re-running the command. If you want the data to be persisted on storage，runtiup --tag playground .... For details, refer toTiUP Reference Guide.

Start a new session to access TiDB:

Use the TiUP client to connect to TiDB.


                   
                    tiup client

You can also use the MySQL client to connect to TiDB.


                   
                    mysql --host 127.0.0.1 --port 4000 -u root

Access the Prometheus dashboard of TiDB athttp://127.0.0.1:9090.
Access theTiDB Dashboardathttp://127.0.0.1:2379/dashboard. The default username isroot, with an empty password.
(Optional)Load data to TiFlashfor analysis.

Clean up the cluster after the test deployment:

Stop the process by pressingctrl - c.

Run the following command:


                   
                    tiup clean --all

Note

TiUP Playground listens on127.0.0.1by default, and the service is only locally accessible. If you want the service to be externally accessible, specify the listening address using the--hostparameter to bind the network interface card (NIC) to an externally accessible IP address.

作为一个分布式系统,基本TiDB测试集群usually consists of 2 TiDB instances, 3 TiKV instances, 3 PD instances, and optional TiFlash instances. With TiUP Playground, you can quickly build the test cluster by taking the following steps:

Download and install TiUP:


                 
                  curl --proto'=https'--tlsv1.2 -sSf https://tiup-mirrors.m.rzhenli.com/install.sh | sh

Declare the global environment variable:

Note

After the installation, TiUP displays the absolute path of the correspondingprofilefile. You need to modify the followingsourcecommand according to the path.


                 
                  source.bash_profile

Start the cluster in the current session:

If you want to start a TiDB cluster of the latest version with 1 TiDB instance, 1 TiKV instance, 1 PD instance, and 1 TiFlash instance, run the following command:


                   
                    tiup playground

If you want to specify the TiDB version and the number of the instances of each component, run a command like this:


                   
                    tiup playground v4.0.16 --db 2 --pd 3 --kv 3 --monitor

The command downloads a version cluster to the local machine and starts it，such as v4.0.16.--monitormeans that the monitoring component is also deployed.

To view the latest version, runtiup list tidb.

This command returns the access methods of the cluster:


                   
                    CLUSTER START SUCCESSFULLY, Enjoy it ^-^ To connect TiDB: mysql --host 127.0.0.1 --port 4000 -u root To connect TiDB: mysql --host 127.0.0.1 --port 4001 -u root To view the dashboard: http://127.0.0.1:2379/dashboard To view the monitor: http://127.0.0.1:9090

Note

For the playground operated in this way, after the test deployment is finished, TiUP will clean up the original cluster data. You will get a new cluster after re-running the command. If you want the data to be persisted on storage，runtiup --tag playground .... For details, refer toTiUP Reference Guide.

Start a new session to access TiDB:

Use the TiUP client to connect to TiDB.


                   
                    tiup client

You can also use the MySQL client to connect to TiDB.


                   
                    mysql --host 127.0.0.1 --port 4000 -u root

Access the Prometheus dashboard of TiDB athttp://127.0.0.1:9090.
Access theTiDB Dashboardathttp://127.0.0.1:2379/dashboard. The default username isroot, with an empty password.
(Optional)Load data to TiFlashfor analysis.

Clean up the cluster after the test deployment:

Stop the process by pressingctrl - c.

Run the following command:


                   
                    tiup clean --all

Note

TiUP Playground listens on127.0.0.1by default, and the service is only locally accessible. If you want the service to be externally accessible, specify the listening address using the--hostparameter to bind the network interface card (NIC) to an externally accessible IP address.

Simulate production deployment on a single machine

Scenario: Experience the smallest TiDB cluster with the complete topology and simulate the production deployment steps on a single Linux server.

This section describes how to deploy a TiDB cluster using a YAML file of the smallest topology in TiUP.

Prepare

Prepare a target machine that meets the following requirements:

CentOS 7.3 or a later version is installed
The Linux OS has access to the Internet, which is required to download TiDB and related software installation packages

The smallest TiDB cluster topology is as follows:

Note:

The IP address of the following instances only serves as an example IP. In your actual deployment, you need to replace the IP with your actual IP.

Instance	Count	IP	配置
TiKV	3	10.0.1.1 10.0.1.1 10.0.1.1	Avoid conflict between the port and the directory
TiDB	1	10.0.1.1	The default port Global directory configuration
PD	1	10.0.1.1	The default port Global directory configuration
TiFlash	1	10.0.1.1	The default port Global directory configuration
Monitor	1	10.0.1.1	The default port Global directory configuration

Other requirements for the target machine:

Therootuser and its password is required
Stop the firewall service of the target machine, or open the port needed by the TiDB cluster nodes
Currently, TiUP supports deploying TiDB on the x86_64 (AMD64 and ARM) architectures:
- It is recommended to use CentOS 7.3 or later versions on AMD64
- It is recommended to use CentOS 7.6 1810 on ARM

Deploy

Note

你可以登录到the target machine as a regular user or therootuser. The following steps use therootuser as an example.

Download and install TiUP:


                
                 curl --proto'=https'--tlsv1.2 -sSf https://tiup-mirrors.m.rzhenli.com/install.sh | sh

Declare the global environment variable.

Note

After the installation, TiUP displays the absolute path of the correspondingprofilefile. You need to modify the followingsourcecommand according to the path.


                
                 source.bash_profile

Install the cluster component of TiUP:


                
                 tiup cluster

If the TiUP cluster is already installed on the machine, update the software version:


                
                 tiup update --self && tiup update cluster

Use therootuser privilege to increase the connection limit of thesshdservice. This is because TiUP needs to simulate deployment on multiple machines.

Modify/etc/ssh/sshd_config, and setMaxSessionsto20.

Restart thesshdservice:


                  
                   service sshd restart

Create and start the cluster:

Edit the configuration file according to the following template, and name it astopo.yaml:


                
                 # # Global variables are applied to all deployments and used as the default value of
                 # # the deployments if a specific deployment value is missing.
                 global:
                 user:
                 "tidb"
                 ssh_port:
                 22
                 deploy_dir:
                 "/tidb-deploy"
                 data_dir:
                 "/tidb-data"
                 # # Monitored variables are applied to all the machines.
                 monitored:
                 node_exporter_port:
                 9100
                 blackbox_exporter_port:
                 9115
                 server_configs:
                 tidb:
                 log.slow-threshold:
                 300
                 tikv:
                 readpool.storage.use-unified-pool:
                 false
                 readpool.coprocessor.use-unified-pool:
                 true
                 pd:
                 replication.enable-placement-rules:
                 true
                 replication.location-labels:["host"]tiflash:
                 logger.level:
                 "info"
                 pd_servers:
                 -
                 host:
                 10.0
                 .1
                 .1
                 tidb_servers:
                 -
                 host:
                 10.0
                 .1
                 .1
                 tikv_servers:
                 -
                 host:
                 10.0
                 .1
                 .1
                 port:
                 20160
                 status_port:
                 20180
                 config:
                 server.labels:{host:
                 "logic-host-1"}-
                 host:
                 10.0
                 .1
                 .1
                 port:
                 20161
                 status_port:
                 20181
                 config:
                 server.labels:{host:
                 "logic-host-2"}-
                 host:
                 10.0
                 .1
                 .1
                 port:
                 20162
                 status_port:
                 20182
                 config:
                 server.labels:{host:
                 "logic-host-3"}tiflash_servers:
                 -
                 host:
                 10.0
                 .1
                 .1
                 monitoring_servers:
                 -
                 host:
                 10.0
                 .1
                 .1
                 grafana_servers:
                 -
                 host:
                 10.0
                 .1
                 .1

user: "tidb": Use thetidbsystem user (automatically created during deployment) to perform the internal management of the cluster. By default, use port 22 to log in to the target machine via SSH.
replication.enable-placement-rules: This PD parameter is set to ensure that TiFlash runs normally.
host: The IP of the target machine.

Execute the cluster deployment command:


                
                 tiup cluster deploy   ./topo.yaml --user root -p

: Set the cluster name
: Set the TiDB cluster version. You can see all the supported TiDB versions by running thetiup list tidbcommand

Enter "y" and therootuser's password to complete the deployment:


                
                 Do you want to continue? [y/N]: y Input SSH password:

Start the cluster:


                
                 tiup cluster start

Access the cluster:

Install the MySQL client. If it is already installed, skip this step.


                  
                   yum -y install mysql

Access TiDB. The password is empty:


                  
                   mysql -h 10.0.1.1 -P 4000 -u root

Access the Grafana monitoring dashboard athttp://{grafana-ip}:3000. The default username and password are bothadmin.
Access theTiDB Dashboardathttp://{pd-ip}:2379/dashboard. The default username isroot, and the password is empty.

To view the currently deployed cluster list:


                  
                   tiup cluster list

To view the cluster topology and status:


                  
                   tiup cluster display

What's next

If you have just deployed a TiDB cluster for the local test environment:
- LearnBasic SQL operations in TiDB
- Migrate data to TiDB
If you are ready to deploy a TiDB cluster for the production environment:
If you're looking for analytics solution with TiFlash:
- Use TiFlash
- TiFlash Overview

Note

By default, TiDB, TiUP and TiDB Dashboard share usage details with PingCAP to help understand how to improve the product. For details about what is shared and how to disable the sharing, seeTelemetry.

Download PDF Request docs changes Ask questions on Discord

Playground

New

One-stop & interactive experience of TiDB's capabilities WITHOUT registration.