How to Install TiDB Database: Step-by-Step Guide

TiDB is an open-source distributed SQL database that combines the best features of traditional relational databases and NoSQL stores. It supports horizontal scalability, strong consistency, and high availability, making it suitable for OLTP and OLAP workloads. This guide provides you with detailed steps on how to install TiDB on your system.

Prerequisites

A Linux-based operating system (recommended: Ubuntu 20.04 or CentOS 7/8)
At least 2 CPUs and 4GB RAM per TiDB node for production; minimal requirements for development machines may be lower
Docker installed (optional for quick local deployment)
Basic command line proficiency
Network connectivity between nodes if installing a cluster
TiDB Official Site for latest releases and documentation (Official site)

Step 1: Choose Deployment Method

You can deploy TiDB using several methods depending on your use case:

Docker-based single node – quick local testing
Binary deployment – manual control for single/multi-node
TiUP – the official package manager for TiDB clusters
Kubernetes-based deployment – modern production clusters

For simplicity, this tutorial uses TiUP, the most common and recommended installation tool.

Step 2: Install TiUP

TiUP is a useful cluster management and deployment tool designed by the TiDB team.

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

After installation, add TiUP to your current shell environment:

source ~/.bash_profile

Verify TiUP installation:

tiup --version

Step 3: Prepare System Requirements

Ensure ports 4000, 2379, 2380, 9090, 9100 are open and not blocked by firewall.
Set system’s network and kernel parameters optimized for TiDB if needed (advanced users).

Step 4: Deploy a TiDB Cluster

Now deploy a basic TiDB cluster on your local machine for testing:

tiup cluster deploy tidb-test v7.4.0 ./my-cluster.yaml

The file my-cluster.yaml defines your cluster topology. For example, a simple configuration might look like this:

global:
  user: tidb
  ssh_port: 22
  deploy_dir: /tidb-deploy
  data_dir: /tidb-data

server_configs: {}

pd_servers:
  - host: 127.0.0.1
    client_port: 2379
    peer_port: 2380

tidb_servers:
  - host: 127.0.0.1
    port: 4000

tikv_servers:
  - host: 127.0.0.1
    port: 20160

monitoring_servers:
  - host: 127.0.0.1
    port: 9090

Next, start the cluster:

tiup cluster start tidb-test

Step 5: Verify TiDB Installation

Use the mysql client to connect to the TiDB server:

mysql -h 127.0.0.1 -P 4000 -u root

Run some sample SQL queries to confirm everything is functional.

Step 6: Managing Your TiDB Cluster

Use tiup cluster status tidb-test to check cluster health.
Stop the cluster with tiup cluster stop tidb-test.
Upgrade or scale your cluster using TiUP commands.

Troubleshooting Tips

If TiUP commands fail, ensure it is installed correctly and in your PATH.
Check firewall rules if ports are unreachable.
Review TiDB logs under /tidb-deploy directories for errors.
Ensure you have required system permissions for deployment.

Summary Checklist

Installed TiUP package manager
Configured cluster YAML
Deployed and started TiDB cluster
Verified functionality with MySQL client
Monitored cluster status and logs

For comparing TiDB installation with other databases, check our How to Install Vitess Database: Step-by-Step Guide to explore another distributed database system.

TiDB offers high scalability and flexibility. Following these steps will let you quickly set up, test, and manage your own TiDB cluster for development or production workloads.