🐥

TiDB Cloud : Cloud API を使った クラスター操作 その２ Essential 版

に公開
TiDB
cloudapi
tech

https://zenn.dev/kameoncloud/articles/061200e7199902
今日は前回操作したβ提供中のTiDB Cloud API を続いて使っていきます。
前回の記事ではStarter（旧Serverless）クラスターを使用しましたがデータアックアップリストア等がサポートされていませんでした。
Essential用APIの定義がなくStarterとDedicatedのみに対応していたため、中の人に聞いたところAPI自体がバージョンアップしており(v1beta→v1beta1)新たにEssential用コマンドが生えていました！
https://docs.pingcap.com/tidbcloud/api/v1beta1/serverless/#tag/Cluster/operation/ClusterService_CreateCluster

この記事ではEseentialクラスターでいろいろな機能を試していきます。
Starterでは行えなかった以下がサポートされているようです。

さっそくやってみる

0. 事前準備

まずは前回同様この記事をもとにIAM APIを使ってキーを発行しておきます。
https://zenn.dev/kameoncloud/articles/1b27bc40db70a5

1. Essential クラスターの起動

では早速クラスターを起動します。

cat << 'EOF' > payload.json
{
  "displayName": "essential-full-demo",
  "region": {
    "name": "regions/aws-us-west-2"
  },
  "servicePlan": "Essential",
  "spendingLimit": {
    "monthly": 50
  },
  "automatedBackupPolicy": {
    "startTime": "00:00",
    "retentionDays": 7
  },
  "endpoints": {
    "public": {
      "disabled": false,
      "authorizedNetworks": [
        {
          "startIpAddress": "0.0.0.0",
          "endIpAddress": "255.255.255.255",
          "displayName": "allow-all"
        }
      ]
    }
  },
  "rootPassword": "my-shining-password-123",
  "encryptionConfig": {
    "enhancedEncryptionEnabled": true
  },
  "highAvailabilityType": "ZONAL",
  "version": "latest",
  "labels": {
    "tidb.cloud/project": "1372813089454531804"
  },
  "autoScaling": {
    "minRcu": 2000,
    "maxRcu": 4000
  }
}
EOF

curl --location "https://serverless.tidbapi.com/v1beta1/clusters" \
  --digest --user "$TIDB_CLOUD_PUBLIC_KEY:$TIDB_CLOUD_PRIVATE_KEY" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data-binary @payload.json

response
{
  "name": "clusters/10456368633481255855",
  "clusterId": "10456368633481255855",
  "displayName": "essential-full-demo",
  "region": {
    "name": "regions/aws-us-west-2",
    "regionId": "us-west-2",
    "cloudProvider": "aws",
    "displayName": "Oregon (us-west-2)",
    "provider": "aws",
    "servicePlans": []
  },
  "endpoints": {
    "public": {
      "host": "",
      "port": 0,
      "disabled": false,
      "authorizedNetworks": []
    },
    "private": {
      "host": "",
      "port": 0
    }
  },
  "rootPassword": "",
  "encryptionConfig": {
    "enhancedEncryptionEnabled": true
  },
  "highAvailabilityType": "ZONAL",
  "version": "",
  "createdBy": "apikey-02LMUCD0",
  "userPrefix": "",
  "state": "CREATING",
  "labels": {
    "tidb.cloud/organization": "1372813089209216952",
    "tidb.cloud/project": "1372813089454531804"
  },
  "annotations": {
    "tidb.cloud/available-features": "DISABLE_PUBLIC_LB,DELEGATE_USER",
    "tidb.cloud/has-set-password": "false"
  },
  "createTime": "2025-11-06T07:38:46.198Z",
  "updateTime": "2025-11-06T07:38:46.198Z",
  "auditLogConfig": {
    "enabled": false,
    "unredacted": false
  },
  "autoScaling": {
    "minRcu": 2000,
    "maxRcu": 4000
  },
  "servicePlan": "Essential"
}

レスポンスの中にCluser IDが含まれていますのでメモしておきます。

2. データのエクスポート

では次にデータのエクスポートを試します。からデータベースはエクスポートが行えませんので以下のコマンドでダミーデータを書き込んでおきます。

CREATE DATABASE sampledb;
USE sampledb;
CREATE TABLE users (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    name VARCHAR(100),
    email VARCHAR(255),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
INSERT INTO users (name, email)
VALUES
  ('Alice', 'alice@example.com'),
  ('Bob', 'bob@example.com'),
  ('Charlie', 'charlie@example.com');
SELECT * FROM users;

次に以下のコマンドでデータエクスポートを実行します。

cat << 'EOF' > export.json
{
  "exportOptions": {
    "fileType": "SQL",
    "compression": "GZIP"
  },
  "target": {
    "type": "LOCAL"
  },
  "displayName": "SNAPSHOT_{snapshot_time}"
}
EOF

curl --location "https://serverless.tidbapi.com/v1beta1/clusters/${CLUSTER_ID}/exports" \
  --digest --user "$TIDB_CLOUD_PUBLIC_KEY:$TIDB_CLOUD_PRIVATE_KEY" \
  --header "Content-Type: application/json" \
  --data-binary @export.json

このコマンドではSQL形式のファイルをGZIPで圧縮しローカル（TiDB Cloudのクラスター側）に保存します。
コマンドの実行結果として以下の様なレスポンスが戻ります。

レスポンス
{
  "exportId": "exp-ovchb6in6zeshopmbt5mlt44wm",
  "name": "clusters/10456368633481255855/exports/exp-ovchb6in6zeshopmbt5mlt44wm",
  "clusterId": "10456368633481255855",
  "createdBy": "apikey-02LMUCD0",
  "state": "RUNNING",
  "exportOptions": {
    "fileType": "SQL",
    "database": "*",
    "table": "*",
    "compression": "GZIP",
    "filter": null
  },
  "target": {
    "type": "LOCAL"
  },
  "displayName": "SNAPSHOT_{snapshot_time}",
  "createTime": "2025-11-06T08:02:12.869Z",
  "snapshotTime": "2025-11-06T08:02:12.526Z"
}

::: details
以下がエクスポートされたファイルになります。
"name": "clusters/10456368633481255855/exports/exp-ovchb6in6zeshopmbt5mlt44wm"
次のコマンドでエクスポートジョブのステータスが確認できます。

curl --location "https://serverless.tidbapi.com/v1beta1/clusters/10456368633481255855/exports/exp-ovchb6in6zeshopmbt5mlt44wm" \
  --digest --user "$TIDB_CLOUD_PUBLIC_KEY:$TIDB_CLOUD_PRIVATE_KEY"
Response
{
  "exportId": "exp-ovchb6in6zeshopmbt5mlt44wm",
  "name": "clusters/10456368633481255855/exports/exp-ovchb6in6zeshopmbt5mlt44wm",
  "clusterId": "10456368633481255855",
  "createdBy": "apikey-02LMUCD0",
  "state": "SUCCEEDED",
  "exportOptions": {
    "fileType": "SQL",
    "database": "*",
    "table": "*",
    "compression": "GZIP",
    "filter": null
  },
  "target": {
    "type": "LOCAL"
  },
  "displayName": "SNAPSHOT_{snapshot_time}",
  "createTime": "2025-11-06T08:02:13Z",
  "updateTime": "2025-11-06T08:04:29Z",
  "completeTime": "2025-11-06T08:03:44Z",
  "snapshotTime": "2025-11-06T08:02:12.526Z",
  "expireTime": "2025-11-08T08:03:44Z"
}

このサンプルではLOCALを指定しましたがS3など外部ストレージを指定することも可能です。

次回予告

次回の記事ではS3へのデータエクスポートとインポートを纏めて試したいと思います。

Discussion