В этом руководстве показано, как установить TiDB с помощью TiUP, запустить локальный кластер, подключиться к нему через MySQL-клиент и выполнить первые запросы в Ubuntu и RHEL-подобных системах Linux. Если вам приходилось сталкиваться с ограничениями масштабирования MySQL за пределами одного узла записи, TiDB предлагает решение, не требующее изучения нового языка запросов. TiDB использует протокол MySQL, поэтому с ним работают существующие приложения, драйверы, ORM и даже стандартный клиент mysql. Запустим TiDB.

Что такое TiDB

TiDB — это распределённая SQL-база данных с открытым исходным кодом, разработанная компанией PingCAP. Она разделяет вычисления и хранение на отдельные компоненты:

  • TiDB обрабатывает SQL-запросы и клиентские соединения.

  • TiKV хранит данные.

  • PD (Placement Driver) управляет кластером и обеспечивает согласованную работу всех частей.

Благодаря независимой работе этих компонентов можно масштабировать ресурсы хранения и вычислений по отдельности, а не обновлять единый сервер. Поэтому TiDB хорошо подходит для приложений, работающих с большими объёмами данных и растущими нагрузками.

По мере роста базы данных MySQL один сервер со временем может стать узким местом. TiDB решает эту проблему, распределяя данные по нескольким узлам и сохраняя совместимость с MySQL.

Это означает, что вы можете продолжать использовать привычный синтаксис SQL, существующие клиенты MySQL, драйверы и приложения, не изучая новый язык запросов и не переписывая код.

Руководство протестировано на Ubuntu 26.04 LTS и Rocky Linux 9.5, но те же шаги подходят для большинства современных 64‑битных дистрибутивов Linux. На момент написания статьи актуальной стабильной версией является TiDB 8.5.7.

Прежде чем начать, учтите, что TiDB 8.4 и более новые версии больше не поддерживают RHEL 7. Если вы всё ещё используете одну из этих ОС, перед установкой TiDB потребуется обновить систему до поддерживаемого выпуска, например Rocky Linux 9.1 или новее.

Шаг 1: Установка TiUP, пакетного менеджера TiDB

Для установки или развёртывания TiDB сначала потребуется TiUP, официальный пакетный менеджер экосистемы TiDB. TiUP упрощает процесс, загружая и управляя необходимыми компонентами при создании или развёртывании кластера.

Благодаря этому вам не нужно загружать или настраивать TiDB, TiKV, PD и другие компоненты вручную.

Чтобы установить TiUP, выполните следующую команду на Ubuntu, Debian, RHEL, Rocky Linux или любом другом поддерживаемом 64‑битном дистрибутиве Linux:

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

Эта команда делает следующее:

  • curl скачивает установочный скрипт с сервера PingCAP.

  • --proto '=https' разрешает только HTTPS-соединения, предотвращая небезопасную загрузку по HTTP.

  • --tlsv1.2 требует TLS 1.2 или более новую версию для защищённого соединения.

  • -sSf запускает curl без лишних сообщений, но при этом показывает ошибки и прерывает работу, если загрузка не удалась.

  • | sh передаёт загруженный скрипт напрямую в оболочку для выполнения.

После завершения установки команда tiup помещается в каталог ~/.tiup/bin. Теперь перезагрузите конфигурацию оболочки, чтобы команда tiup стала доступна в текущем сеансе терминала:

source ~/.bashrc

Если вы используете Zsh, перезагрузите её конфигурацию:

source ~/.zshrc

Чтобы убедиться, что TiUP установлена успешно, проверьте версию:

tiup --version

Результат должен выглядеть примерно так:

tiup version 1.x.x

Если вы получаете ошибку tiup: command not found, убедитесь, что каталог ~/.tiup/bin добавлен в переменную PATH вашей оболочки. Установщик обычно автоматически обновляет ~/.bashrc, но если вы работаете в другой оболочке, например Zsh, возможно, придётся добавить путь вручную.

Шаг 2: Запуск локального кластера TiDB

После установки TiUP можно запустить локальный кластер TiDB с помощью компонента playground. Он автоматически поднимает все основные сервисы TiDB, включая TiDB, TiKV, PD и TiFlash, что даёт самый быстрый способ опробовать TiDB на собственной машине.

Запустите игровой кластер командой:

tiup playground

При первом запуске TiUP загружает все необходимые компоненты, поэтому процесс может занять несколько минут в зависимости от скорости интернет‑соединения.

После успешного старта вы увидите подобный вывод:

🎉 Игровой кластер TiDB Playground запущен, приятной работы!

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

Важная деталь: по умолчанию TiDB слушает порт 4000, а не стандартный порт MySQL 3306. Если попытаться подключиться к порту 3306, соединение не установится.

По умолчанию игровой кластер слушает только адрес 127.0.0.1, то есть принимает подключения только с локальной машины. Если вы запускаете TiDB на удалённом сервере и хотите подключаться с другого компьютера, используйте:

tiup playground --host 0.0.0.0

При этом убедитесь, что брандмауэр сервера разрешает доступ к порту 4000 для нужных систем.

Шаг 3: Подключение к TiDB с помощью MySQL‑клиента

Поскольку TiDB совместим с протоколом MySQL, подключиться к нему можно с помощью стандартного MySQL‑клиента. Отдельный клиент не требуется.

Если MySQL‑клиент ещё не установлен, установите его:

  • На Ubuntu или Debian:
sudo apt install mysql-client -y
  • На RHEL или Rocky Linux:
sudo dnf install mysql -y

sudo выполняет установку с правами администратора, которые необходимы для установки системных пакетов. Без этого установка не пройдёт из‑за нехватки прав.

После установки клиента подключитесь к запущенному кластеру:

mysql --host 127.0.0.1 --port 4000 -u root

При успешном подключении откроется приглашение MySQL:

Welcome to the MySQL monitor...

mysql>

Обратите внимание, что подключение идёт к порту 4000 — стандартному SQL‑порту TiDB. Локальный игровой кластер не требует пароля для пользователя root, поэтому вход произойдёт сразу. Для локальной тестовой среды это нормально и предназначено для облегчения изучения и разработки.

В промышленной среде всегда следует защищать учётную запись root и настраивать полноценную аутентификацию перед допуском пользователей.

Шаг 4: Выполнение первых запросов

Теперь создадим базу данных, добавим таблицу, вставим данные и убедимся, что всё работает корректно.

В приглашении mysql> выполните следующие команды SQL:

CREATE DATABASE rootpathdb;

USE rootpathdb;

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;

Если всё работает правильно, вы увидите похожий результат:

+----+----------+----------+
| id | hostname | role     |
+----+----------+----------+
|  1 | web01    | frontend |
|  2 | db01     | backend  |
+----+----------+----------+
2 rows in set

Как видите, работа с TiDB ощущается так же, как и с MySQL. Вы используете те же SQL‑операторы для создания баз данных и таблиц, вставки данных и выполнения запросов. Существующие знания MySQL и инструменты работают без изменений, что позволяет легко начать использовать TiDB.

Развёртывание TiDB за пределами локального playground

Кластер tiup playground предназначен для обучения и тестирования. Он запускает временный кластер TiDB, работающий на переднем плане. После остановки кластер и его данные удаляются, если только вы не использовали опцию --tag для сохранения данных.

Для среды разработки, тестирования или промышленной эксплуатации необходимо развернуть полноценный кластер с помощью команды tiup cluster deploy. Этот метод использует YAML‑файл топологии, в котором указывается, на каких серверах будут работать компоненты TiDB, TiKV и PD. Затем TiUP подключается к этим серверам по SSH и автоматически устанавливает кластер.

Если вы развёртываете TiDB на сервере, принимающем внешние подключения, убедитесь, что порт SQL (4000) открыт в брандмауэре.

  • На системах Ubuntu или Debian с UFW:
sudo ufw allow 4000/tcp
  • На системах RHEL или Rocky Linux с firewalld:
sudo firewall-cmd --permanent --add-port=4000/tcp
sudo firewall-cmd --reload

После настройки брандмауэра удалённые клиенты смогут подключаться к TiDB по порту 4000, если сервер настроен на приём внешних соединений.

Если вы ещё не работали с firewalld, изучите наше руководство по настройке firewalld в Linux, чтобы разобраться с зонами и созданием постоянных правил.

После развёртывания TiDB как промышленного кластера управление его сервисами выполняется так же, как и любыми другими службами systemd. Взгляните на руководство по команде systemctl, чтобы узнать, как запускать, останавливать, перезапускать службы и включать их при загрузке.

Распространённые ошибки и способы их решения

Если при настройке TiDB возникают проблемы, вот самые частые из них и способы исправления.

Connection refused на порту 3306

Если MySQL‑клиент сообщает об ошибке подключения к порту 3306, скорее всего, вы пытаетесь соединиться со стандартным портом MySQL.

Игровой кластер TiDB по умолчанию слушает порт 4000, поэтому подключайтесь так:

mysql --host 127.0.0.1 --port 4000 -u root

Permission denied при установке

Если вы видите ошибку Permission denied во время установки MySQL‑клиента, значит, менеджер пакетов не получил права администратора.

Запустите установку с sudo:

sudo apt install mysql-client -y

или для RHEL‑совместимых систем:

sudo dnf install mysql -y

Если после установки команда tiup не находится, оболочка ещё не подхватила обновлённый PATH.

Перезагрузите конфигурацию оболочки:

source ~/.bashrc

Если используется Zsh, выполните:

source ~/.zshrc

Если проблема не исчезла, убедитесь, что каталог ~/.tiup/bin добавлен в переменную окружения PATH вашей оболочки. Открытие нового сеанса терминала также автоматически перезагрузит обновлённую среду.

Заключение

Вы успешно установили TiUP, запустили локальный кластер TiDB, подключились к нему с помощью стандартного MySQL‑клиента и выполнили первые SQL‑запросы. Благодаря совместимости TiDB с протоколом MySQL можно использовать тот же синтаксис и многие знакомые инструменты, что упрощает начало работы.

Освоившись в среде playground, попробуйте запустить более крупный локальный кластер, чтобы увидеть, как работает распределённая архитектура TiDB.