TiDBをローカル環境で動かすTiUP playground徹底解説

はじめに

「TiDB、興味はあるんですけどローカルで動かしても意味ないですよね？分散DBですもんね？」という声をわりと多くいただきます。惜しい。TiDBをローカル環境で動かすTiUP playgroundはTiDBの動作を確認する最高のツールですし、TiDBの設定パラメーターや挙動のデバッグをするツールでもあります。

この記事ではTiUP playgroundの基本的な使い方から、設定変更の方法、ログの確認方法など応用を解説します。実行環境はMacOSです。(おそらくLinux/WSLでも同様に動作すると思いますが、確認はしていません）

起動まで

まず、TiUPコマンド自体をインストールします。ミラーサイトからセットアップスクリプトをダウンロードして実行します。
実行時に.bashrc等にパスを設定するので、実行後ログインしなおすか、source ~/.bashrc 等でリフレッシュしてください。

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

その後TiUP playgroundを起動します。

TiUPは様々な管理ツールの親コマンドになっています。playgroundはサブコマンドの一つです。他にもTiDBクラスタの管理を行うclusterコマンドや、TiDB Serverlessクラスタの管理ができるcloudコマンドがあります。

> tiup playground v8.1.0

Note: Version constraint  is resolved to v8.1.0. If you'd like to use other versions:

    Use exact version:      tiup playground v7.1.0
    Use version range:      tiup playground ^5
    Use nightly:            tiup playground nightly

Start pd instance:v8.1.0
Start tikv instance:v8.1.0
Start tidb instance:v8.1.0
Waiting for tidb instances ready
127.0.0.1:4000 ... Done
Start tiflash instance:v8.1.0
Waiting for tiflash instances ready
127.0.0.1:3930 ... Done

🎉 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

これで、TiDBクラスタの立ち上げは完了です。この状態で下記の操作が可能です。

• mysqlクライアントからの接続
  • 上の出力にあるオプションで接続できます。TiDBのポートのデフォルトは4000でMySQLとは異なるので注意してください。
• TiDB Dashboard(Web管理画面)のログイン
  • Slow QueryやTop SQLが確認できるダッシュボードです。ユーザー名/パスワードは上記MySQL接続と同じです。
• Grafana(メトリクス)ログイン
  • メトリクスのGrafanaダッシュボードに接続できます。初期ユーザーはadmin/adminです。

これでTiDBを試すことができます。この状態でもアプリケーションの動作確認や学習用途では十分ですが、TiDB自身の設定確認や動作確認には物足りないです。そのような方は応用編にいきましょう。

Playground応用編

ヘルプを見る

コマンドのヘルプは tiup playground --help で確認できます。すべてのコマンドの説明はここに記載されています。
本当に多くの設定が可能です。本記事はその中でも（個人的に）よく使うものを解説しています。

Grafanaを起動しない

Grafanaのデフォルト起動ポートがRuby on Railsのデフォルトポートと被っているので、立ち上げたくないときもあると思います。そんなときは --without-monitor オプションを指定することでGrafanaを起動しないように設定できます。

Grafanaの起動ポートを指定するオプションもあり、--grafana.port int でGrafanaの起動ポートを変更できます

TiDBのバージョンを指定する

TiDBには様々なバージョンがあり、バージョン間の違いを確認したいケースもあります。そのような場合はplaygroundでバージョンを指定することが可能です。

# バージョンを指定して実行
tiup playground v7.5.2

バージョンの確認は、tiup listコマンドで、tidbコンポーネントのバージョン一覧を出力させて行います。

> tiup list tidb

Version                          Installed  Release                              Platforms
-------                          ---------  -------                              ---------
nightly -> v8.2.0-alpha-nightly             2024-06-22T06:45:17Z                 darwin/amd64,darwin/arm64,linux/amd64,linux/arm64
v3.0.0                                      2020-04-16T14:03:31+08:00            darwin/amd64,linux/amd64
v3.0                                        2020-04-16T16:58:06+08:00            darwin/amd64,linux/amd64
v3.0.1                                      2020-04-27T19:38:36+08:00            darwin/amd64,linux/amd64,linux/arm64
...

コンポーネントの台数を指定する

標準ではtidbx1, tikvx1, pdx1, tiflashx1のそれぞれ一つのプロセスが起動します。主要コンポーネントだと

• tidb: --db <台数> で指定
• tikv: --kv <台数> で指定
• pd: --pd <台数> で指定
• tiflash: --tiflash <台数> で指定
• tiproxy: --tiproxy <台数> で指定

となります。サンプルとして、標準的なTiDBクラスタの構成で起動する例を記載します。

> tiup playground --tiproxy 1 --db 2 --kv 3 --pd 3 --tiflash 1

...省略...
🎉 TiDB Playground Cluster is started, enjoy!

Connect TiDB:    mysql --comments --host 127.0.0.1 --port 4000 -u root
Connect TiDB:    mysql --comments --host 127.0.0.1 --port 4001 -u root
Connect TiProxy: mysql --comments --host 127.0.0.1 --port 6000 -u root
TiDB Dashboard:  http://127.0.0.1:2379/dashboard
Grafana:         http://127.0.0.1:3000

TiProxyを指定した場合は、mysqlクライアントの接続はTiProxyに対して行います。（上記の例だと6000番ポート)

クラスタの状態を確認する

playgroundはローカルでそれぞれのコンポーネントプロセスを起動しています。tiup playground display コマンドでそのリストを確認することができます。このコマンドはtiup playground を起動した状態で実行する必要があるので、別のターミナルから実行してください。

> tiup playground display

Pid    Role     Uptime
---    ----     ------
29765  pd       4m21.424481s
29766  pd       4m21.362440917s
29767  pd       4m21.277711s
29768  tikv     4m21.211529792s
29769  tikv     4m21.152029041s
29770  tikv     4m21.08453975s
29771  tidb     4m21.021516666s
29772  tidb     4m20.965984958s
29773  tiproxy  4m20.955863167s
29800  tiflash  4m3.16460525s

ここで表示されるPidをスケールインのときに利用します。

クラスタのスケールイン

クラスタのスケールインも可能です。これは実質pidを指定してkillしているようなもので、1台しかないコンポーネントにも適用可能です。tiup playground scale-in --pid <pid> で実行します。

> tiup playground scale-in --pid 29771

scale in tidb success

上記の例はtidbですが、任意のコンポーネントのpidが指定可能です

クラスタのスケールアウト

スケールインと同様に、スケールアウトして台数を増やすことができます。クラスタ作成時に台数を指定するのと同様のオプションを使って増やす台数を指定できます。

下記はTiDBを1台、TiKVを1台増やす例です。

> tiup playground scale-out --db 1 --kv 1
To connect new added TiDB: mysql --comments --host 127.0.0.1 --port 4000 -u root -p (no password)

サーバ設定の適用

TiDBやTiKV、PDなどのそれぞれのコンポーネントはtomlファイルで起動パラメーターを設定するようになっています。この設定をplaygroundでも指定することが可能です。

それぞれ、下記のパラメーターで設定ファイルを指定します。

• TiDB: --db.config
• TiKV: --kv.config
• PD: --pd.config
• TiFlash: --tiflash.config
• TiProxy: --tiproxy.config

それぞれの設定ファイルドキュメントへのリンク

• TiDB: https://docs.pingcap.com/tidb/stable/tidb-configuration-file
• TiKV: https://docs.pingcap.com/tidb/stable/tikv-configuration-file
• PD: https://docs.pingcap.com/tidb/stable/pd-configuration-file
• TiFlash: https://docs.pingcap.com/tidb/stable/tiflash-configuration
• TiProxy: https://docs.pingcap.com/tidb/stable/tiproxy-configuration

なお、設定はplaygroundで一部上書きされるため、全部の設定が有効になるわけではありません。

わかりやすい例として、サーバのバージョン文字列を指定するserver-versionを指定したtomlを読み込ませてみます。

tidb.version.toml

server-version = "Playground version 10.0"

> tiup playground --db.config ./tidb.version.toml

...省略...
🎉 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

別のコンソールから接続してみます

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

Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 555745286
Server version: Playground version 10.0 TiDB Server (Apache License 2.0) Community Edition, MySQL 8.0 compatible

設定した Playground version 10.0 が表示されていることがわかります。

コンポーネントのログを確認する

playgroundで取得したコンポーネントのバイナリや、ログ、TiKVのデータなどは ~/.tiup/ に保存されています。~/.tiup/data フォルダに各コンポーネントのログやデータがあるので、ここからログを確認します。
例えばTiDBのログファイルなら、~/.tiup/data/<タグ名>/tidb-0/tidb.log にあります。

TiUPは起動毎に一意のタグを付与して、そのタグ名で~/.tiup/data/の下に作業ディレクトリを作成します。
このディレクトリは毎回削除されるため、残しておきたい場合は明示的にタグを指定してください。

タグを指定する (データを保存する)

TiUPは起動毎にタグ名を適当に決めて、毎回作業ディレクトリを作成しますが、タグ名を明示的に指定することで作業ディレクトリを残すことができます。これにより、TiKVで入れたデータなどを保存することができるようになります。

逆に明示的に消さないと残り続けるので注意してください。不要になったら tiup cleanコマンドを使って削除してください。

タグを指定して起動するのは、tiup playground -T <タグ名> で可能です。

おわりに

以上のオプションを使って、TiDBのクラスタ時の挙動やオプションの動作などを確認するのにplaygroundを活用することができます。是非試してみてください。また、「こういうことがしたいんだけど・・・」みたいな質問などがあれば X:@bohnen にお気軽にメンションください！