This tutorial shows you how to install TiDB using TiUP, start a local cluster, connect to it with the MySQL client, and run your first queries on Ubuntu and RHEL-based Linux systems.
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.
What Is TiDB
TiDB is an open-source distributed SQL database developed by PingCAP. It separates computing and storage into different components:
- TiDB handles SQL queries and client connections.
- TiKV stores the data.
- PD (Placement Driver) manages the cluster and keeps everything working together.
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.
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.
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.
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.
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.
If TiDB’s separate-node architecture has you thinking about high availability and scaling, share this tutorial with a teammate who’s still relying on a single MySQL server
Step 1: Install TiUP, the TiDB Package Manager
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.
This means you don’t have to download or configure TiDB, TiKV, PD, or other components manually.
To install TiUP, run the following command on Ubuntu, Debian, RHEL, Rocky Linux, or any other supported 64-bit Linux distribution:
curl --proto '=https' --tlsv1.2 -sSf https://tiup-mirrors.pingcap.com/install.sh | sh
Here’s what this command does:
curldownloads the installation script from PingCAP’s server.--proto '=https'allows only HTTPS connections, preventing insecure HTTP downloads.--tlsv1.2requires TLS 1.2 or a newer version for a secure connection.-sSfruns curl quietly, but still displays errors and stops if the download fails.| shsends the downloaded script directly to the shell for execution.
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:
source ~/.bashrc
If you’re using Zsh, reload its configuration instead:
source ~/.zshrc
To confirm that TiUP was installed successfully, check its version:
tiup --version
You should see output similar to this:
tiup version 1.x.x
If you get a tiup: command not found error, make sure ~/.tiup/bin has been added to your shell’s PATH. The installer normally updates ~/.bashrc automatically, but if you’re using another shell such as Zsh, you may need to add it to your shell configuration file manually.
Step 2: Start a Local TiDB Cluster
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.
Start the playground cluster by running:
tiup playground
The first time you run this command, TiUP downloads all the required components, so it may take a few minutes depending on your internet connection.
Once the cluster starts successfully, you’ll see output similar to this:
🎉 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
The important detail here is that TiDB listens on port 4000 by default, not the standard MySQL port 3306. If you try connecting with a MySQL client configured for port 3306, the connection will fail.
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:
tiup playground --host 0.0.0.0
If you do this, make sure your server’s firewall allows access to port 4000 from the systems that need to connect.
Step 3: Connect to TiDB with the MySQL Client
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.
If you don’t already have the MySQL client installed, install it first.
On Ubuntu or Debian, run:
sudo apt install mysql-client -y
On RHEL or Rocky Linux, run:
sudo dnf install mysql -y
The sudo command runs the installation with administrator privileges, which are required to install system packages. Without it, the installation will fail due to insufficient permissions.
Once the MySQL client is installed, connect to your running TiDB playground cluster:
mysql --host 127.0.0.1 --port 4000 -u root
If the connection is successful, you’ll see the MySQL prompt:
Welcome to the MySQL monitor... mysql>
Notice that you’re connecting to port 4000, which is TiDB’s default SQL port.
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.
In a production deployment, you should always secure the root account and configure proper authentication before allowing users to connect.
Step 4: Run Your First Queries
Now let’s create a database, add a table, insert some data, and verify that everything is working correctly.
At the mysql> prompt, run the following SQL commands:
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;
If everything is working correctly, you’ll see output similar to this:
+----+----------+----------+ | id | hostname | role | +----+----------+----------+ | 1 | web01 | frontend | | 2 | db01 | backend | +----+----------+----------+ 2 rows in set
As you can see, working with TiDB feels just like working with MySQL. You use the same SQL statements to create databases and tables, insert data, and query records. Existing MySQL knowledge and tools work without any changes, making it easy to get started with TiDB.
If it surprised you that the same MySQL commands work on a distributed TiDB cluster, share this tutorial with someone who’s still debating whether to manually shard MySQL or switch to a database that’s designed to scale out from the start.
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.
Deploying TiDB Beyond a Local Playground
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.
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.
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.
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.
If you’re deploying TiDB on a server that accepts remote connections, make sure the SQL port (4000) is allowed through the firewall.
On Ubuntu or Debian systems using UFW, run:
sudo ufw allow 4000/tcp
On RHEL or Rocky Linux systems using firewalld, run:
sudo firewall-cmd --permanent --add-port=4000/tcp sudo firewall-cmd --reload
After the firewall is configured, remote clients can connect to TiDB on port 4000, provided the server is configured to accept external connections.
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.
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.
If you’re deciding whether to keep testing locally or deploy a real TiDB cluster, share this tutorial with your team before making the call.
Common Errors to Watch For
If you run into problems while setting up TiDB, here are the most common ones and how to fix them.
Connection refused on port 3306
If your MySQL client reports a connection error on port 3306, you’re probably trying to connect to the default MySQL port.
The TiDB playground listens on port 4000 by default, so connect using:
mysql --host 127.0.0.1 --port 4000 -u root
Permission denied during installation
If you see a Permission denied error while installing the MySQL client, the package manager wasn’t run with administrator privileges.
Run the installation command with sudo:
sudo apt install mysql-client -y
or on RHEL-based systems:
sudo dnf install mysql -y
If the tiup command isn’t found after installation, your shell hasn’t picked up the updated PATH yet.
Reload your shell configuration:
source ~/.bashrc
If you’re using Zsh, run:
source ~/.zshrc
If the problem persists, verify that the ~/.tiup/bin directory has been added to your shell’s PATH environment variable. Opening a new terminal session also reloads the updated environment automatically.
If this guide saved you from wondering why TiDB wouldn’t connect on port 3306, share it with the next person who ends up searching for “TiDB port 4000” after midnight.
Conclusion
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.
Once you’re comfortable with the playground environment, try starting a larger local cluster to see how TiDB’s distributed architecture works:
If this article helped, with someone on your team.
