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.
TiDB is an open-source distributed SQL database developed by PingCAP.
It separates computing and storage into different components:
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.
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:
Here’s what this command does:
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:
If you’re using Zsh, reload its configuration instead:
To confirm that TiUP was installed successfully, check its version:
You should see output similar to this:
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.
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:
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:
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:
If you do this, make sure your server’s firewall allows access to port 4000 from the systems that need to connect.
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:
On RHEL or Rocky Linux, run:
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:
If the connection is successful, you’ll see the MySQL prompt:
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.
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:
If everything is working correctly, you’ll see output similar to this:
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 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.
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:
On RHEL or Rocky Linux systems using firewalld, run:
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 run into problems while setting up TiDB, here are the most common ones and how to fix them.
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:
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:
or on RHEL-based systems:
If the tiup command isn’t found after installation, your shell hasn’t picked up the updated PATH yet.
Reload your shell configuration:
If you’re using Zsh, run:
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.
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:
lazygit: Manage Git Repositories from the Linux Terminal
Hister: Search Local Files Instantly in Linux
Prometheus TSDB: Manage Data Storage and Retention on Linux
Yazi: Fast Rust-Based Terminal File Manager for Linux
herdr: A Terminal Tool for Managing Multiple AI Coding Agents
Flyline: Add Syntax Highlighting, Fuzzy Search, and AI to Bash
How to Monitor Remote Linux Systems with Glances
How to Monitor Ubuntu Performance Using Netdata
How to Install Zabbix Monitoring Tool on Debian 11/10
5 Modern VnStat PHP Replacements for Bandwidth Monitoring
10 Tips On How to Use Wireshark to Analyze Packets in Your Network
How to Monitor Linux Server Security with Osquery
How to Set or Change System Hostname in Linux
watch: The One Linux Command You Keep Forgetting to Use
7 Best Tools to Compare Text Files in Linux
How to Find Deleted Files Still Eating Disk Space
How to Convert CSV File to TSV File in Linux
3 Ways to Permanently and Securely Delete ‘Files and Directories’ in Linux
5 Best Mathematical Equation and Formula Writing Tools for Linux
5 Best Open-Source PDF Annotation Tools for Linux in 2024
27 Best Tools for VMware Administrators in 2024
8 Best Open Source Web Servers in 2024
10 Best Clipboard Managers for Linux
16 Best Tools to Access Remote Linux Desktop
—
**📚 Original Source:**
[TiDB: Build a MySQL-Compatible Distributed SQL Database on Linux](https://www.tecmint.com/tidb-distributed-sql-database-linux/)
About The Author
