Run the installation command with sudo:
What Is TiDB
+—-+———-+———-+
| id | hostname | role |
+—-+———-+———-+
| 1 | web01 | frontend |
| 2 | db01 | backend |
+—-+———-+———-+
2 rows in set
As a MySQL database grows, a single server can eventually become a bottleneck. TiDB solves this by distributing data across multiple nodes while remaining compatible with MySQL.
If your MySQL client reports a connection error on port 3306, you’re probably trying to connect to the default MySQL port.
tiup version 1.x.x
To install TiUP, run the following command on Ubuntu, Debian, RHEL, Rocky Linux, or any other supported 64-bit Linux distribution:
This means you don’t have to download or configure TiDB, TiKV, PD, or other components manually.
Step 1: Install TiUP, the TiDB Package Manager
Once TiDB is deployed as a production cluster, you’ll manage its services just like any other systemd service. See our systemctl command guide to learn how to start, stop, restart, and enable services at boot.
Before you begin, note that TiDB 8.4 and later no longer support RHEL 7. If you’re still using either of those operating systems, you’ll need to upgrade to a supported release, such as Rocky Linux 9.1 or later, before installing TiDB.
When the installation finishes, the tiup command is installed in the ~/.tiup/bin directory. Now reload your shell configuration so the tiup command is available in the current terminal session:
sudo apt install mysql-client -y
source ~/.zshrc
source ~/.bashrc
Once you’re comfortable with the playground environment, try starting a larger local cluster to see how TiDB’s distributed architecture works:
If you’re deploying TiDB on a server that accepts remote connections, make sure the SQL port (4000) is allowed through the firewall.
curl –proto ‘=https’ –tlsv1.2 -sSf https://tiup-mirrors.pingcap.com/install.sh | sh
sudo dnf install mysql -y
By default, the playground cluster listens only on 127.0.0.1, which means it accepts connections only from the local machine. If you’re running TiDB on a remote server and want to connect from another computer, start it with:
If you’ve ever struggled to scale MySQL beyond a single write node, TiDB offers a solution without requiring you to learn a new query language. It uses the MySQL protocol, so your existing applications, drivers, ORMs, and even the mysql client work with it. Let’s get TiDB up and running.
sudo dnf install mysql -y
Since TiDB is compatible with the MySQL protocol, you can connect to it using the standard MySQL client. There’s no need to install a separate client.
As you move beyond a local test setup, you’ll also need to know how to manage remote servers, secure SSH access, configure firewalls, and administer Linux services.
If you run into problems while setting up TiDB, here are the most common ones and how to fix them.
Step 3: Connect to TiDB with the MySQL Client
The local playground cluster does not require a password for the root user, so you’ll be logged in immediately. This is normal for a local test environment and is meant to make learning and development easier.
sudo firewall-cmd –permanent –add-port=4000/tcp
sudo firewall-cmd –reload
TiDB is an open-source distributed SQL database developed by PingCAP. It separates computing and storage into different components:
CREATE DATABASE tecmintdb;
USE tecmintdb;
CREATE TABLE servers (
id INT PRIMARY KEY,
hostname VARCHAR(50),
role VARCHAR(20)
);
INSERT INTO servers VALUES
(1, ‘web01’, ‘frontend’),
(2, ‘db01’, ‘backend’);
SELECT * FROM servers;
With TiUP installed, you can start a local TiDB cluster using the playground component. It automatically launches all the core TiDB services, including TiDB, TiKV, PD, and TiFlash, making it the quickest way to try TiDB on your own machine.
In a production deployment, you should always secure the root account and configure proper authentication before allowing users to connect.
For development, testing, or production environments, you should deploy a real TiDB cluster using tiup cluster deploy. This deployment method uses a topology YAML file to define which servers will run the TiDB, TiKV, and PD components. TiUP then connects to those servers over SSH and installs the cluster automatically.
If you already know MySQL, getting started with TiDB feels familiar. If you need a refresher on the basics, check out TecMint’s guide on creating and managing MySQL databases and tables.
sudo apt install mysql-client -y
tiup playground
🎉 TiDB Playground Cluster is started, enjoy!
Connect TiDB: mysql –comments –host 127.0.0.1 –port 4000 -u root
TiDB Dashboard: http://127.0.0.1:2379/dashboard
Grafana: http://127.0.0.1:3000
At the mysql> prompt, run the following SQL commands:
You have successfully installed TiUP, started a local TiDB cluster, connected to it using the standard MySQL client, and run your first SQL queries. Since TiDB is compatible with the MySQL protocol, you can use the same SQL syntax and many of the same tools you’re already familiar with, making it easy to get started.
This means you can continue using familiar SQL syntax, existing MySQL clients, drivers, and applications without learning a new query language or rewriting your code.
If you’re new to firewalld, check out our guide on how to configure firewalld in Linux to learn about firewall zones and creating permanent rules.
Deploying TiDB Beyond a Local Playground
The SSH Course at Pro TecMint covers these essential skills, making it a practical next step before deploying and managing TiDB in a real server environment.
mysql –host 127.0.0.1 –port 4000 -u root
Before you can install or deploy TiDB, you first need TiUP, the official package manager for the TiDB ecosystem. TiUP simplifies the installation process by downloading and managing the required TiDB components whenever you create or deploy a cluster.
mysql –host 127.0.0.1 –port 4000 -u root
Permission denied during installation
Welcome to the MySQL monitor…
mysql>
If you don’t already have the MySQL client installed, install it first.
The TiDB playground listens on port 4000 by default, so connect using:
On Ubuntu or Debian, run:
tiup playground –host 0.0.0.0
Start the playground cluster by running:
Common Errors to Watch For
Reload your shell configuration:
Connection refused on port 3306
sudo ufw allow 4000/tcp
Now let’s create a database, add a table, insert some data, and verify that everything is working correctly.
Once the cluster starts successfully, you’ll see output similar to this:
source ~/.bashrc
This tutorial was tested on Ubuntu 26.04 LTS and Rocky Linux 9.5, but the same steps work on most modern 64-bit Linux distributions. TiDB 8.5.7 is the current stable release at the time of writing.
Because these components run independently, you can scale storage or computing resources separately instead of upgrading a single server. This makes TiDB a good choice for applications that need to handle large amounts of data and growing workloads.
Once the MySQL client is installed, connect to your running TiDB playground cluster:
source ~/.zshrc
tiup –version
On Ubuntu or Debian systems using UFW, run:
The tiup playground cluster is designed for learning and testing. It starts a temporary TiDB cluster that runs in the foreground. When you stop it, the cluster and its data are removed unless you start it with a --tag option to preserve the data.
