Local TiDB Installation - Building a Test Environment

Tags:

Building a Local Test Cluster

Scenario: use a single macOS or Linux server to quickly build a local TiDB cluster for testing. Deploying this kind of cluster helps you learn TiDB’s basic architecture and the operation of components such as TiDB, TiKV, PD, and monitoring components.

As a distributed system, a basic TiDB test cluster generally consists of two TiDB instances, three TiKV instances, three PD instances, and optional TiFlash instances. With TiUP Playground, you can quickly build a test cluster by following the steps below.

1. Download and install TiUP

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

If the following message appears, TiUP has been installed successfully.

Successfully set mirror to https://tiup-mirrors.pingcap.com
Detected shell: zsh
Shell profile:  /Users/user/.zshrc
/Users/user/.zshrc has been modified to add tiup to PATH
open a new terminal or source /Users/user/.zshrc to use it
Installed path: /Users/user/.tiup/bin/tiup
===============================================
Have a try:     tiup playground
===============================================

Remember the shell profile path in the output above. You need to use it in the next step.

After installation, TiUP displays the absolute path of the corresponding shell profile file. Depending on the path, replace ${your_shell_profile} in the following source command. In this case, ${your_shell_profile} from the output in step 1 is /Users/user/.zshrc.

source ${your_shell_profile}

2. Start the cluster in the current session

To start the latest version of a TiDB cluster with a single TiDB instance, a single TiKV instance, a single PD instance, and a single TiFlash instance, run the following command.

tiup playground

To specify the TiDB version and the number of instances for each component, run a command similar to the following.

tiup playground v6.1.0 --db 2 --pd 3 --kv 3

This command downloads and starts a versioned cluster such as v6.1.0 on the local machine. To see the latest versions, run tiup list tidb.

This command returns ways to access the cluster.

CLUSTER START SUCCESSFULLY, Enjoy it ^-^
To connect TiDB: mysql --comments --host 127.0.0.1 --port 4001 -u root -p (no password)
To connect TiDB: mysql --comments --host 127.0.0.1 --port 4000 -u root -p (no password)
To view the dashboard: http://127.0.0.1:2379/dashboard
PD client endpoints: [127.0.0.1:2379 127.0.0.1:2382 127.0.0.1:2384]
To view Prometheus: http://127.0.0.1:9090
To view Grafana: http://127.0.0.1:3000

3. Start a new session to access TiDB

Connect to TiDB using the TiUP client.

tiup client

When you run it for the first time, you can see that the required client is installed as shown below.

[kimkc@localhost ~]$ tiup client
tiup is checking updates for component client ...
A new version of client is available:
The latest version:         v1.11.0
Local installed version:
Update current component:   tiup update client
Update all components:      tiup update --all

The component `client` version  is not installed; downloading from repository.
download https://tiup-mirrors.pingcap.com/client-v1.11.0-linux-amd64.tar.gz 49.3
download https://tiup-mirrors.pingcap.com/client-v1.11.0-linux-amd64.tar.gz 304.
download https://tiup-mirrors.pingcap.com/client-v1.11.0-linux-amd64.tar.gz 644.
download https://tiup-mirrors.pingcap.com/client-v1.11.0-linux-amd64.tar.gz 1.45
download https://tiup-mirrors.pingcap.com/client-v1.11.0-linux-amd64.tar.gz 2.38
download https://tiup-mirrors.pingcap.com/client-v1.11.0-linux-amd64.tar.gz 3.87
download https://tiup-mirrors.pingcap.com/client-v1.11.0-linux-amd64.tar.gz 4.49
MiB / 4.49 MiB 100.00% 4.24 MiB/s
Starting component `client`: /home/kimkc/.tiup/components/client/v1.11.0/tiup-client
[kimkc@localhost ~]$

Then an endpoint selection screen appears as follows.

┌─Choose a endpoint to connect─────────────────────────────────────────────────┐
│ TLr4XQE mysql://root@127.0.0.1:4000                                          │
│ TLr4XQE mysql://root@127.0.0.1:4001                                          │
└──────────────────────────────────────────────────────────────────────────────┘

Press Enter on the green item to select it. Here, port 4000 was selected.

Then a console like the following appears.

my:root@127.0.0.1:4000=>

Perhaps because it is highly compatible with MySQL, the word my stands out.

Now run the MySQL command show databases;.

my:root@127.0.0.1:4000=> show databases;
Database
--------------------
INFORMATION_SCHEMA
METRICS_SCHEMA
PERFORMANCE_SCHEMA
mysql
test
(5 rows)

You can see that it is displayed as above.

  • You can also connect to TiDB using the MySQL client.
mysql --host 127.0.0.1 --port 4000 -u root

3. Other connection checks

  • Access the TiDB Prometheus dashboard at http://127.0.0.1:9090.
  • Access the TiDB dashboard at http://127.0.0.1:2379/dashboard.
    • The default username is root, and the password is empty.
  • Access the TiDB Grafana dashboard at http://127.0.0.1:3000.
    • The default username and password are both admin.
  • Optional: load analytical data into TiFlash.

4. Clean up the cluster after test deployment

  1. Press Control+C to stop the TiDB service above.
  2. After the service stops, run the following command.
tiup clean --all

References