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 macOS and Linux)
• Simulate production deployment on a single machine (for Linux only)

Deploy a local test cluster

• Scenario: Quickly deploy a local TiDB cluster for testing using a single macOS 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.

• macOS
• Linux

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:

Other requirements for the target machine:

• The root user and its password is required

• Stop the firewall service of the target machine, or open the port needed by the TiDB cluster nodes

• Currently, the TiUP cluster 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

1. Download and install TiUP:

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

2. Declare the global environment variable.

   Note

   After the installation, TiUP displays the absolute path of the corresponding Shell profile file. You need to modify ${your_shell_profile} in the following source command according to the path.

   source ${your_shell_profile}
   

3. Install the cluster component of TiUP:

   tiup cluster
   

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

   tiup update --self && tiup update cluster
   

5. Use the root user privilege to increase the connection limit of the sshd service. This is because TiUP needs to simulate deployment on multiple machines.

   1. Modify /etc/ssh/sshd_config, and set MaxSessions to 20.

   2. Restart the sshd service:

      service sshd restart
      

6. Create and start the cluster:

   Edit the configuration file according to the following template, and name it as topo.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:
      instance.tidb_slow_log_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 the tidb system 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.

7. Execute the cluster deployment command:

   tiup cluster deploy <cluster-name> <tidb-version> ./topo.yaml --user root -p
   

   • <cluster-name>: Set the cluster name

   • <tidb-version>: Set the TiDB cluster version. You can see all the supported TiDB versions by running the tiup list tidb command

   • -p: Specify the password used to connect to the target machine.

     Note

     If you use secret keys, you can specify the path of the keys through -i. Do not use -i and -p at the same time.

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

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

8. Start the cluster:

   tiup cluster start <cluster-name>
   

9. 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 at http://{grafana-ip}:3000. The default username and password are both admin.

   • Access the TiDB Dashboard at http://{pd-ip}:2379/dashboard. The default username is root, 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 <cluster-name>
     

What's next

• If you have just deployed a TiDB cluster for the local test environment:

  • Learn Basic SQL operations in TiDB
  • Migrate data to TiDB

• If you are ready to deploy a TiDB cluster for the production environment:

  • Deploy TiDB using TiUP
  • Deploy TiDB on Cloud using TiDB Operator

• If you're looking for analytics solution with TiFlash:

  • Use TiFlash
  • TiFlash Overview