TiDB Cloud CLI (ticloud) の紹介

# はじめに

:::note warn
最新版はこちらです https://qiita.com/bohnen/items/5f9a2ad9c8f5ae36c439
:::

TiDB Serverlessは実はCLIからも操作することができます。
この記事では便利なTiDB Cluod CLIの紹介をします。MacOSを利用していますが、Linux/WSLでも同じように使えると思います。

## インストールと設定

### TiDB Cloud CLIのインストール

TiDB Cloud CLIのセットアップツールを使う方法と、[TiUP](https://docs.pingcap.com/ja/tidb/stable/tiup-reference)を利用する方法があります。TiUPを利用した場合はTiUPのサブコマンドとして利用することになります。今回は、セットアップツールを利用してセットアップします。ターミナルからcurlでセットアップスクリプトを取得し実行します。

```bash
curl https://raw.githubusercontent.com/tidbcloud/tidbcloud-cli/main/install.sh | sh
```
シェルを自動判別して、PATH環境変数にticloudコマンドの場所を追記しています。再読み込みします。
```bash
source ~/.zshrc
```

これでticloudコマンドが利用できるはずです。

### APIキーの取得

TiDB Cloud コンソールからAPIキーを発行します。TiDB Cloudにログインし、左下にあるビルのアイコンから、`Organization Settings` を選びます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/12495/53822b56-131d-f0f9-2faf-432d01732b74.png)

`API Keys`と書かれたタブをクリックして、`Create API Key`ボタンを押します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/12495/611baf78-7f33-e2e0-33a0-675ae246e943.png)

APIキーが生成されます。PublicとPrivateの両方のキーをメモしておきます。
![スクリーンショット 2023-12-18 20.34.19.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/12495/1101aa9a-3d40-b8c4-4b95-677a0bd3bd88.png)

### プロファイルの作成

ターミナルに戻り、ticloudコマンドを使ってプロファイルを作成します。
```bash
> ticloud config create
Check the https://docs.pingcap.com/tidbcloud/api/v1beta#section/Authentication/API-Key-Management for more information about how to create API keys.
> demo     # プロファイル名
> XXPUBLIC # APIキー Public
> •••••••••••••••••••••••••••••••••••• #APIキー Private
```
なおプロファイル名は大文字を指定しても全て小文字になるようです。

プロファイルが作成できたら、これをアクティブプロファイルにします。
```bash
ticloud config use demo
```
### オートコンプリート設定（オプション）

TiUPもそうなのですが、TiDBのCLIはだいたいオートコンプリートが設定できるようになっています。ticloudコマンドも可能です。詳細は `ticloud completion zsh -h` で確認できますが、ここではセッションでオートコンプリートを有効にします。

```bash
source <(ticloud completion zsh); compdef _ticloud ticloud
```

これでサブコマンド入力前やコマンド途中でのTabを使った補完がきくようになります。便利〜とおもいきや、後述のようにticloudはinteractiveモードがあり、オプションをinteractiveに指定出来るのであまり必要ないかもしれません。

## ticloud 利用法

ここからは順に使い方を見ていきます。

### クラスタ操作 - ticloud cluster

クラスタを作成したり、削除したりする基本コマンドです。
```text
connect-info  -- Get connection string for the specified cluster
create        -- Create one cluster in the specified project
delete        -- Delete a cluster from your project
describe      -- Describe a cluster
list          -- List all clusters in a project
```

基本はcreate, connect-info でしょうか。見ていきます。

```bash
> ticloud cluster create
Choose the cluster type:
> [x] SERVERLESS
Choose the cloud provider:
> [x] AWS
Choose the cloud region:
> [x] ap-northeast-1
> mycluster
> ••••••••

[ Submit ]

●∙∙ Waiting for cluster to be ready
Cluster 100XXXXXXXXXXXXX is ready.
```
クラスタの作成は ticloud cluster createでインタラクティブに実施できます。現在のところSERVERLESSにしか対応しておらず、SERVERLESSはAWS固定なのでリージョンの指定くらいです。TiDB Cloudコンソールでのcluster作成と異なり、パスワードの指定が可能です。

```bash
> ticloud cluster connect-info
Choose the cluster
> [x] mycluster(100XXXXXXXXXXXXX)
Choose the client
> [x] MySQL CLI
Choose the operating system
> [x] macOS/Alpine (Detected)

mysql -u 'XXXXXXXXXXX.root' -h gateway01.ap-northeast-1.prod.aws.tidbcloud.com -P 4000 -D test --ssl-mode=VERIFY_IDENTITY --ssl-ca=/etc/ssl/cert.pem --comments -p${password}
```
connect-infoでは、接続するためのコマンドラインや接続文字列を取得できます。実は後述のconnectサブコマンドがあるのでticloud自体から接続出来てしまうのですが、その他のツールや言語からの接続の確認に便利です。

### 接続 - ticloud connect

ticloudからTiDB clusterに接続します。内部的に[usql](https://github.com/xo/usql)を利用しているようで、コマンドの操作感はmysql cliとは異なります。

```bash
> ticloud connect
Choose the cluster
> [x] mycluster(100XXXXXXXXXXXXX)
? Use the default user? Yes
Current user: XXXXXXXXXXXX.root
Enter password:
Connected with driver mysql (5.7.25-TiDB-v6.6.0-serverless)
Type "help" for help.

XXXXXXXXXXX.root@mycluster/test=>
```

### データインポート - ticloud import

ticloudからローカル、S3にあるファイルのインポートを行えます。また、mysql cliを使ったMySQLからのデータインポートにも対応しているようです。（初めて知りました）
```text
  cancel      Cancel a data import task
  describe    Describe a data import task
  list        List data import tasks
  start       Start an import task
```

適当なCSVファイルをインポートしてみます。
```bash
> ticloud import start local employees_data.csv
Choose the cluster
> [x] mycluster(100XXXXXXXXXXXXX)
Choose the data format:
> [x] CSV
> test
> employees

[ Submit ]

? Do you need to custom CSV format? No
∙●∙ Uploading file
File has been uploaded
∙∙● Starting import task
Import task 1188766 started.
```
テーブルは存在していませんでしたが、CSVファイルのヘッダから作成してくれるようです。ただ、インポート後に定義を確認したところ、TiDB Cloudコンソールでは指定できるようなPrimary Keyの設定などはできません。テーブルをあらかじめ作るか、柔軟に設定したければTiDB Cloudコンソールを利用した方がよさそうです。

アップロードジョブの状況は、listで確認できます。

```bash
> ticloud import list
Choose the cluster
> [x] mycluster(100XXXXXXXXXXXXX)

ID       Type   Status     CreatedAt                 Source              DataFormat  Size
1188766  LOCAL  COMPLETED  2023-12-18T12:51:47.000Z  employees_data.csv  CSV         0 B
```

## まとめ

TiDB Cloud cli (ticloud) の設定と利用について説明しました。他にもオプションがありますが、ヘルプやインタラクティブモードがかなり親切であまり苦労せず利用できそうです。是非試してみてください。