💭

TiDB Cloud : Cloud API を使った クラスター操作 その3 Essential 版 S3 へのエクスポートインポート

に公開
TiDB
cloudapi
essential
tech

https://zenn.dev/kameoncloud/articles/aa1c1f7fab3544
今日は前回に引き続きCloud API v1beta1 を活用してEssentialクラスターを操作していきます。

この記事ではAmazon S3 へデータをエクスポートしたのち、インポートを行ってみます。

さっそくやってみる

0. 事前準備

まずは前回の記事に基づきEssentialクラスタを操作可能なIAM API キーの発行とEssentialクラスターの作成、テスト用データ書き込みまでを終わらせておきます。
https://zenn.dev/kameoncloud/articles/aa1c1f7fab3544

1. AWS 側の環境準備

まずは適当なS3バケットを作成します。
s3://tidbkameping/essential/
次にS3バケットの操作権限を保有するIAMユーザーを作成し、アクセスキーとシークレットアクセスキーを発行して手元にメモしておきます。

2. エクスポートコマンドの実行

以下のコマンドを実行します。

cat << 'EOF' > export-s3.json
{
  "exportOptions": {
    "fileType": "SQL",
    "compression": "GZIP",
    "filter": {
      "table": {
        "patterns": [
          "sampledb.users"
        ]
      }
    }
  },
  "target": {
    "type": "S3",
    "s3": {
      "uri": "S3_URI_PLACEHOLDER",
      "authType": "ACCESS_KEY",
      "accessKey": {
        "id": "AWS_ACCESS_KEY_PLACEHOLDER",
        "secret": "AWS_SECRET_PLACEHOLDER"
      }
    }
  },
  "displayName": "S3_EXPORT_{snapshot_time}"
}
EOF

# JSON の置換
sed -i "s|S3_URI_PLACEHOLDER|${S3_URI}|g" export-s3.json
sed -i "s|AWS_ACCESS_KEY_PLACEHOLDER|${AWS_ACCESS_KEY_ID}|g" export-s3.json
sed -i "s|AWS_SECRET_PLACEHOLDER|${AWS_SECRET_ACCESS_KEY}|g" export-s3.json

# エクスポート実行
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" \
  --header "Accept: application/json" \
  --data-binary @export-s3.json

以下のようなレスポンスが出力されれば成功です、

{
  "exportId": "exp-4udqq6eifzb4hf5luwofistvdm",
  "name": "clusters/10456368633481255855/exports/exp-4udqq6eifzb4hf5luwofistvdm",
  "clusterId": "10456368633481255855",
  "createdBy": "apikey-02LMUCD0",
  "state": "RUNNING",
  "exportOptions": {
    "fileType": "SQL",
    "database": "",
    "table": "",
    "compression": "GZIP",
    "filter": {
      "table": {
        "patterns": [
          "sampledb.users"
        ],
        "where": ""
      }
    }
  },
  "target": {
    "type": "S3",
    "s3": {
      "bucketUri": "s3://tidbkameping/essential/",
      "uri": "s3://tidbkameping/essential/",
      "authType": "ACCESS_KEY",
      "accessKey": {
        "id": "AKIA5LIXG4WVNYFRDOQO",
        "secret": ""
      }
    }
  },
  "displayName": "S3_EXPORT_{snapshot_time}",
  "createTime": "2025-11-07T03:05:26.041Z",
  "snapshotTime": "2025-11-07T03:05:25.456Z"
}

"exportId": "exp-4udqq6eifzb4hf5luwofistvdm",
をメモしておきます。

curl --location 'https://serverless.tidbapi.com/v1beta1/clusters/10456368633481255855/exports/exp-4udqq6eifzb4hf5luwofistvdm' --digest --user "$TIDB_CLOUD_PUBLIC_KEY:$TIDB_CLOUD_PRIVATE_KEY" --header 'Accept: applicatio
n/json'

を実行するとエクスポートジョブのステータスが確認できます。10456368633481255855はCluserID、exp-4udqq6eifzb4hf5luwofistvdmはExportIDですのでそれぞれ皆さんの環境ごとに置き換えてください。

{
  "exportId": "exp-4udqq6eifzb4hf5luwofistvdm",
  "name": "clusters/10456368633481255855/exports/exp-4udqq6eifzb4hf5luwofistvdm",
  "clusterId": "10456368633481255855",
  "createdBy": "apikey-02LMUCD0",
  "state": "SUCCEEDED",
  "exportOptions": {
    "fileType": "SQL",
    "database": "",
    "table": "",
    "compression": "GZIP",
    "filter": {
      "table": {
        "patterns": [
          "sampledb.users"
        ],
        "where": ""
      }
    }
  },
  "target": {
    "type": "S3",
    "s3": {
      "bucketUri": "s3://tidbkameping/essential/",
      "uri": "s3://tidbkameping/essential/",
      "authType": "ACCESS_KEY",
      "accessKey": {
        "id": "AKIA5LIXG4WVNYFRDOQO",
        "secret": ""
      }
    }
  },
  "displayName": "S3_EXPORT_{snapshot_time}",
  "createTime": "2025-11-07T03:05:26Z",
  "updateTime": "2025-11-07T03:07:56Z",
  "completeTime": "2025-11-07T03:07:17Z",
  "snapshotTime": "2025-11-07T03:05:25.456Z"
}

statusを見ると無事成功しています。
S3バケットに以下の様にデータがPUTされています。

3. インポートコマンドの実行

インポートはすでにデータベースにデータが含まれている状態だと失敗するためまずは以下のSQLでデータベースを削除しておきます。

DROP DATABASE sampledb;

以下を実行します。

cat << EOF > import-db.json
{
  "importOptions": {
    "fileType": "SQL"
  },
  "source": {
    "type": "S3",
    "s3": {
      "uri": "s3://tidbkameping/essential/",
      "authType": "ACCESS_KEY",
      "accessKey": {
        "id": "${AWS_ACCESS_KEY_ID}",
        "secret": "${AWS_SECRET_ACCESS_KEY}"
      }
    }
  }
}
EOF
curl --location "https://serverless.tidbapi.com/v1beta1/clusters/${CLUSTER_ID}/imports" \
  --digest --user "$TIDB_CLOUD_PUBLIC_KEY:$TIDB_CLOUD_PRIVATE_KEY" \
  --header "Content-Type: application/json" \
  --data-binary @import-db.json

以下の様なレスポンスが戻れば成功です。

{
  "id": "imp-x2e6cpc42bcqrddswwb755j2hi",
  "name": "clusters/10456368633481255855/imports/imp-x2e6cpc42bcqrddswwb755j2hi",
  "clusterId": "10456368633481255855",
  "totalSize": "0",
  "createTime": "2025-11-07T03:23:39Z",
  "state": "PREPARING",
  "completePercent": 0,
  "message": "",
  "createdBy": "apikey-02LMUCD0",
  "creationDetails": {
    "importOptions": {
      "fileType": "SQL",
      "csvFormat": {
        "separator": ""
      }
    },
    "source": {
      "type": "S3",
      "s3": {
        "uri": "s3://tidbkameping/essential/",
        "authType": "ACCESS_KEY",
        "accessKey": {
          "id": "AKIA5LIXG4WVNYFRDOQO",
          "secret": ""
        }
      }
    }
  },
  "importId": "imp-x2e6cpc42bcqrddswwb755j2hi"
}

"state": "PREPARING",としてインポートタスクが開始されていることがわかります。 "importId": "imp-x2e6cpc42bcqrddswwb755j2hi"がタスク用IDですのでコピーして以下のコマンドっを実行します。

 curl --location "https://serverless.tidbapi.com/v1beta1/clusters/${CLUSTER_ID}/imports/imp-x2e6cpc42bcqrddswwb755j2hi" \
  --digest --user "$TIDB_CLOUD_PUBLIC_KEY:$TIDB_CLOUD_PRIVATE_KEY"

{
  "id": "imp-6qyyk3ey75aynetck6apkmddum",
  "name": "clusters/10456368633481255855/imports/imp-6qyyk3ey75aynetck6apkmddum",
  "clusterId": "10456368633481255855",
  "totalSize": "258",
  "createTime": "2025-11-07T03:28:46Z",
  "completeTime": "2025-11-07T03:29:24Z",
  "state": "COMPLETED",
  "completePercent": 100,
  "message": "",
  "createdBy": "apikey-02LMUCD0",
  "creationDetails": {
    "importOptions": {
      "fileType": "SQL",
      "csvFormat": {
        "separator": ""
      }
    },
    "source": {
      "type": "S3",
      "s3": {
        "uri": "s3://tidbkameping/essential/",
        "authType": "ACCESS_KEY",
        "accessKey": {
          "id": "AKIA5LIXG4WVNYFRDOQO",
          "secret": ""
        }
      }
    }
  },
  "importId": "imp-6qyyk3ey75aynetck6apkmddum"
}

"state": "COMPLETED",となっていればインポート完了です。

Discussion