はじめに
「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
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の起動ポートを指定するオプションを追加したpull requestがHEADにマージされているので、以降のバージョンではポートを指定できるようになる見込みです。
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を読み込ませてみます。
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 にお気軽にメンションください!