tidb-cloud-zero

# Create Disposable TiDB Cloud Zero Databases (Technical Preview)

> **Browser UI Note:** There is no browser-based SQL editor on this site. To run SQL, use API + CLI, or sign in to TiDB Cloud Console (login required).

Use this guide to create disposable TiDB Cloud Zero databases for agent workflows.

## Deterministic SQL Smoke Test (API + CLI)

```bash
# 1) Provision instance
curl -s -X POST https://zero.tidbapi.com/v1alpha1/instances \
  -H "Content-Type: application/json" \
  -d '{"tag":"sql-smoke-test"}' \
  | tee tidb-zero.json

# 2) Extract connection string
jq -r '.instance.connectionString // .connectionString' tidb-zero.json

# 3) Run SQL query (replace <connectionString> with step 2 output)
mysql "<connectionString>" -e "SELECT 1 AS health_check, 2 AS example_value;"
```

Expected output includes one row with `health_check=1` and `example_value=2`.

## Endpoint

- Method: `POST`
- URL: `https://zero.tidbapi.com/v1alpha1/instances`
- Content-Type: `application/json`
- **Technical Preview:** Current API path is `/v1alpha1/instances`, and this path may change in later releases.

## Request Body

- **Optional:** `tag` (caller identifier used for tracing and grouping runs).

```json
{
  "tag": "support-bot"
}
```

## Quick Start

```bash
curl -X POST https://zero.tidbapi.com/v1alpha1/instances \
  -H "Content-Type: application/json" \
  -d '{
    "tag": "agent-run"
  }'
```

## Response

The API returns connection details and expiration time.

- **Current response shape:** top-level `instance`.
- **`instance.connection` fields:** `host`, `port`, `username`, `password`.
- **Use these fields:** `instance.connectionString` for direct URI connection, and `instance.expiresAt` for expiration.
- **Agent note:** After provisioning succeeds, save the instance details to a local file (for example, `tidb-cloud-zero.json`) and remind the user to store the file securely because it contains sensitive credentials.
- **Planned update:** we will provide `claimUrl` in a later v...