Quick Start Guide for the TiDB Database Platform

This guide walks you through the quickest way to get started with TiDB. You will be using TiUP, a package manager in the TiDB ecosystem, to help you run any TiDB cluster component with only a single line of command.


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, see Telemetry.


The deployment method provided in this guide is ONLY FOR quick start, NOT FOR production.

Deploy a local test environment on Mac OS

As a distributed system, a basic TiDB test cluster 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:

  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:


    After the installation, TiUP displays the absolute path of the corresponding profile file. You need to modify the following source command according to the path.

    source .bash_profile
  3. 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 v5.3.0 --db 2 --pd 3 --kv 3

      The command downloads a version cluster to the local machine and starts it, such as v5.3.0. To view the latest version, run tiup list tidb.

      This command returns the access methods of the cluster:

      To connect TiDB: mysql --comments --host --port 4001 -u root -p (no password)
      To connect TiDB: mysql --comments --host --port 4000 -u root -p (no password)
      To view the dashboard:
      PD client endpoints: []
      To view Prometheus:
      To view Grafana:


      • Since v5.2.0, TiDB supports running tiup playground on the machine that uses the Apple M1 chip.
      • 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,run tiup --tag <your-tag> playground .... For details, refer to TiUP Reference Guide.
  4. 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 --port 4000 -u root
  5. Access the Prometheus dashboard of TiDB at

  6. Access the TiDB Dashboard at The default username is root, with an empty password.

  7. (Optional) Load data to TiFlash for analysis.

  8. Clean up the cluster after the test deployment:

    1. Stop the process by pressing ctrl-c.

    2. Run the following command:

      tiup clean --all


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

What's next