TiDB ServerlessのCLI TiCloud徹底解説

## はじめに

この記事は昨年書いたticloud紹介記事のアップデートです。

https://qiita.com/bohnen/items/48bd6fbc5ada6c21a8ed

ticloudはTiDB CloudのCLIコンソールですが、昨年のリリース以来更新を重ねて、非常に便利なツールになっています。特にTiDB CloudのoauthログインとServerless固有機能に対応した点は大きいです。

本記事では`ticloud serverless` の機能について詳細に見ていきたいと思います。

## ticloudのインストール

:::note warn
ticloudはLinux/MacOS用です。WindowsバイナリはないのでWSL2等を利用ください
:::

ticloudにはインストールスクリプトでインストールする方法とtiupでインストールする方法がありますが、tiupでインストールされるバイナリは古いことがあるので前者をおすすめします。

```bash
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です。

```bash
> 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はコマンドやオプションの補完にも対応しています。

```bash
> 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、暗号化の有無を入力します。

```bash
> 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` から確認できます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/12495/2afc5c97-1495-f8cc-fbf3-0f1d8ba02388.png)

```bash
ticloud serverless create --project-id <project-id> --display-name <cluster-name> --region <region>
```

### list/describe

クラスタの一覧を確認したり、クラスタの詳細を取得します。

```list.sh
> 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にも対応しています。

```bash
> 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を控えて置くと良いです。インタラクティブにもできますが、毎回やるのは結構面倒なので直接指定するのが早いです。

```bash
> 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
```

:::note warn 
ここで起動したインポートタスクはWebコンソールの `Import` では表示されないので注意してください。
:::

### エクスポート

serverlessクラスタからデータをエクスポートします。エクスポートもジョブとして実行されるため、下記のサブコマンドがあります。

- create エクスポートジョブの作成
- describe エクスポートジョブの詳細表示
- list エクスポートジョブの一覧
- cancel エクスポートジョブのキャンセル
- download エクスポート結果のダウンロード

ローカルにエクスポートする場合は、`create`でジョブを作成して、`list`で状況確認、状態が`SUCCEEDED`になったら、`download`でダウンロードするという流れになります。

```Create.sh
> 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から選べます。

```list.sh
> 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を指定するのが簡単です。

```download.sh
> 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 を設定します。単位はセントなので気を付けてください。

```bash
> 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](https://github.com/xo/usql) を利用しているようです。これもcluster-idの指定だけでいけるので、cluster-idを覚えておく方が早いです。もちろん、インタラクティブモードも利用できます。

```bash
> 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クラスタを削除します。

```bash
> 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](https://tidb.ai/)をコマンドラインツールから使う機能です。

```bash
> 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クラスタを複数運用するときに便利ですのでぜひ使ってみてください。