はじめに
この記事は昨年書いたticloud紹介記事のアップデートです。
ticloudはTiDB CloudのCLIコンソールですが、昨年のリリース以来更新を重ねて、非常に便利なツールになっています。特にTiDB CloudのoauthログインとServerless固有機能に対応した点は大きいです。
本記事ではticloud serverless の機能について詳細に見ていきたいと思います。
ticloudのインストール
ticloudはLinux/MacOS用です。WindowsバイナリはないのでWSL2等を利用ください
ticloudにはインストールスクリプトでインストールする方法とtiupでインストールする方法がありますが、tiupでインストールされるバイナリは古いことがあるので前者をおすすめします。
curl https://raw.githubusercontent.com/tidbcloud/tidbcloud-cli/main/install.sh | sh
一度インストールした後は ticloud upgrade により最新版に更新できます。
auth(認証)
ticloudの利用時に、利用するTiDB Cloudアカウントで認証を行う必要があります。以前はAPI KEYの取得が必要でしたが、今はoauthログインで利用できます。インタラクティブに使う分にはこちらの方が良いでしょう。
auth login コマンドを入力するとブラウザが開いてTiDB Cloudのログイン画面となります。ログイン後画面にConfirmation Codeが表示されるので、コンソールで表示されているConfirmation Codeと同じことを確認して、ダイアログを進めればOKです。
> ticloud auth login
Attempting to automatically open the authorization page in your default browser.
If the browser does not open or you wish to use a different device to authorize this CLI, open the following URL:
https://tidbcloud.com/oauth/device?user_code=XXXX-XXXX
Confirmation Code: XXXX-XXXX
Successfully logged in.
これで、以降のコマンドを実行する準備が整いました。
completion
ticloudはコマンドやオプションの補完にも対応しています。
> ticloud completion
Generate the autocompletion script for ticloud for the specified shell.
See each sub-commands help for details on how to use the generated script.
Usage:
ticloud completion [command]
Available Commands:
bash Generate the autocompletion script for bash
zsh Generate the autocompletion script for zsh
fish Generate the autocompletion script for fish
powershell Generate the autocompletion script for powershell
それぞれの設定方法は、ticloud completion zsh --help のようにサブコマンドのヘルプで確認できます。
serverlessサブコマンド
それでは、serverlessクラスタを操作する、serverlessサブコマンドを見ていくことにします。以下、インタラクティブモードで実行していきます。個々のオプションについて都度確認されるのが分かると思います。
クラスタの作成 (create)
クラスタの作成は create コマンドです。作成するリージョン、プロジェクト、クラスタ名などの基本情報と、Spending Limit、暗号化の有無を入力します。
> ticloud serverless create
Choose the cloud region:
> [x] Tokyo (ap-northeast-1)
Choose the project:
> [x] Demo(XXXX)
> ticloud-serverless
[ Submit ]
? Set spending limit monthly in USD cents (Example: 10, default is 0)? 100
? Enable Enhanced Encryption at Rest? No
∙∙∙ Waiting for cluster to be ready
Cluster XXXXXXXXXXXXXXX is ready.
>
オプションでも設定できますが、project-idの設定が難しいです。普段project-idを意識することはないと思いますが、WebコンソールのOrganization Settings>Projects から確認できます。
ticloud serverless create --project-id <project-id> --display-name <cluster-name> --region <region>
list/describe
クラスタの一覧を確認したり、クラスタの詳細を取得します。
> ticloud serverless list
Choose the project:
> [x] Demo(XXXXX)
ID DisplayName State Version Cloud Region CreateTime
100725572424543XXXXX ticloud-serverless ACTIVE v7.1.3 aws Tokyo (ap-northeast-1) 2024-12-24T22:41:14Z
108341288947140XXXXX Cluster0 ACTIVE v7.1.3 aws Tokyo (ap-northeast-1) 2024-11-27T06:57:19Z
describeについては省略しますが、はほぼ同じような感じで、個別のクラスタの詳細情報をJSONで返します。クラスタ情報だけではなく組織IDなどの上位階層の情報も返すので、サポートリクエストを送るときに添付するとお役立ちのように思います。
インポート
インポートを実行します。インポートはジョブとして実行されるため、下記のサブコマンドがあります。
- start インポートの開始
- list インポートジョブの一覧表示
- cancel インポートジョブのキャンセル
- describe インポートジョブの詳細表示
インタラクティブモードの実行例は下記です。様々なクラウドストレージが利用できます。ただ、LOCALからはCSVのインポートのみの対応のようです。S3の場合は、sql、parquetにも対応しています。
> ticloud serverless import start
Choose the project:
> [x] Demo(XXXX)
Choose the cluster:
> [x] ticloud-serverless(XXXX)
Choose import source type:
> [x] LOCAL
Choose the source file type:
> [x] CSV
> Local file path
> Target database
> Target table
[ Submit ]
進行状況はlistから確認できます。このときcluster-idが必要になるので、startしたときに表示されるcluster-idを控えて置くと良いです。インタラクティブにもできますが、毎回やるのは結構面倒なので直接指定するのが早いです。
> ticloud serverless import list --cluster-id XXXX
ID SourceType State CreateTime Source FileType Size
imp-owj36ogiefcy3fXXXXXXXXXXXX S3 COMPLETED 2024-12-24T23:10:43Z s3://hoge-hogehoge-hoge-hoge/universe-csv/ CSV 3.8 KiB
ここで起動したインポートタスクはWebコンソールの Import では表示されないので注意してください。
エクスポート
serverlessクラスタからデータをエクスポートします。エクスポートもジョブとして実行されるため、下記のサブコマンドがあります。
- create エクスポートジョブの作成
- describe エクスポートジョブの詳細表示
- list エクスポートジョブの一覧
- cancel エクスポートジョブのキャンセル
- download エクスポート結果のダウンロード
ローカルにエクスポートする場合は、createでジョブを作成して、listで状況確認、状態がSUCCEEDEDになったら、downloadでダウンロードするという流れになります。
> ticloud serverless export create
Choose the project:
> [x] Demo(XXXX)
Choose the cluster:
> [x] ticloud-serverless(XXXX)
Input the display name (optional):
> ticloud-export-example
[ Submit ]
Choose the export target:
> [x] LOCAL
Choose how to filter your data:
> [x] Export all data
Choose the exported file type:
> [x] PARQUET
? Do you want change the default parquet compression algorithm ZSTD No
export exp-mk5vz3vukzeq3iyqzkXXXXX is running now
Exportするときは、Export先の指定とExport対象をテーブルで指定するか、SELECTを直接書いて指定することもできます。また出力形式もCSV、SQL、PARQUETから選べます。
> ticloud serverless export list --cluster-id XXXXX
ID DisplayName State Target File CreateTime
exp-mk5vz3vukzeq3iyqzkk7oXXXXX ticloud-export-example SUCCEEDED LOCAL PARQUET 2024-12-24T23:21:48Z
状態を確認します。Importの時同様、cluster-idを指定するのが簡単です。
> ticloud serverless export download
Choose the project:
> [x] Demo(XXXX)
Choose the cluster:
> [x] ticloud-serverless(XXXXX)
Choose the succeeded local type export:
> [x] ticloud-export-example(exp-mk5vz3vukzeq3iyqzkk7oXXXXXX)
> exp
[ Submit ]
? There are 19 files to download, total size is 63 KiB. Please type yes to download: yes
download universe.moons-schema.sql succeeded
....
download universe.stars.0000000010000.zst.parquet succeeded
62 KiB/~63 KiB (0 B/s) with ~0 files(s) remaining
download summary: succeeded: 19 skipped: 0 failed: 0
Downloadはインタラクティブでオプションを指定しました。複数のファイルをダウンロードして所定のディレクトリに保存します。
spending-limit
ServerlessのSpending limit を設定します。単位はセントなので気を付けてください。
> ticloud serverless spending-limit
Choose the project:
> [x] Demo(XXXX)
Choose the cluster:
> [x] ticloud-serverless(XXXX)
Choose the type of spending limit:
> [x] monthly
> 500
[ Submit ]
set spending limit to 500 cents success
shell
Serverlessクラスタに接続します。接続には usql を利用しているようです。これもcluster-idの指定だけでいけるので、cluster-idを覚えておく方が早いです。もちろん、インタラクティブモードも利用できます。
> ticloud serverless shell --cluster-id XXXX
Current user: XXXX.root
Enter password:
Connected with driver mysql (5.7.28-TiDB-v7.1.3-serverless)
Type "help" for help.
XXXX.root@ticloud-serverless=>help
delete
Serverlessクラスタを削除します。
> ticloud serverless delete
Choose the project:
> [x] Demo(XXXX)
Choose the cluster:
> [x] ticloud-serverless(XXXX)
? Please type yes to confirm: yes
cluster XXXX deleted
ai
tidb.aiをコマンドラインツールから使う機能です。
> ticloud ai
You:
TiDB Cloud cliの機能について簡単に説明してください。
TiDB Bot:
TiDB Cloud CLIは、ターミナルからわずかなコマンドラインでTiDB Cloudを操作できるコマンドラインインターフェースです。このCLIを使用
すると、TiDB Cloudクラスターの管理、データのインポート、その他の操作を簡単に行うことができます。[1]
TiDB Cloud CLIを使用する前に、 ticloud CLIをインストールし、ターミナルからTiDB Cloudクラスターを管理できるように環境を設定しておく必
要があります。[1]
TiDB Cloud CLIにはさまざまなコマンドが用意されており、例えばクラスターの作成、削除、リスト表示、データのインポートなどが可能
です。また、いくつかのコマンドにはインタラクティブモードと非インタラクティブモードの2つのモードが提供されており、使いやすさを向上
させています。[1]
TiDB Cloud CLIを使用するためには、ユーザープロファイルを作成する必要があります。ユーザープロファイルはユーザーに関連付
けられたプロパティのコレクションであり、プロファイル名、公開鍵、秘密鍵などが含まれます。ユーザープロファイルを作成するには、 ticloud
config create コマンドを使用します。[1]
TiDB Cloud CLIを通じてTiDB Cloudリソースを効果的に管理するための手段として、TiDB Cloud CLIは非常に便利なツールであり、詳細
についてはTiDB Cloud CLI Quick StartとTiDB Cloud CLI Referenceを参照してください。[3] もし質問があればお気軽にどうぞ。
[1] get-started-with-cli.md https://docs.pingcap.com/tidbcloud/get-started-with-cli
[2] cli-reference.md https://docs.pingcap.com/tidbcloud/cli-reference
[3] release-notes-2023.md https://docs.pingcap.com/tidbcloud/release-notes-2023
おわりに
ticloudはインタラクティブモードを備えた便利なCLIです。serverlessクラスタを複数運用するときに便利ですのでぜひ使ってみてください。