Create ephemeral TiDB Cloud Zero databases for agent workflows in 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.
# 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 and .
health_check=1example_value=2POSThttps://zero.tidbapi.com/v1alpha1/instancesapplication/json/v1alpha1/instances, and this path may change in later releases.tag (caller identifier used for tracing and grouping runs).{
"tag": "support-bot"
}
curl -X POST https://zero.tidbapi.com/v1alpha1/instances \
-H "Content-Type: application/json" \
-d '{
"tag": "agent-run"
}'
The API returns connection details and expiration time.
instance.instance.connection fields: host, port, username, password.instance.connectionString for direct URI connection, and instance.expiresAt for expiration.tidb-cloud-zero.json) and remind the user to store the file securely because it contains sensitive credentials.claimUrl in a later version. Users will be able to sign in to TiDB Cloud and claim the temporary database before instance.expiresAt, converting it into a formal TiDB Cloud Starter database.{
"instance": {
"connection": {
"host": "<HOST>",
"port": 4000,
"username": "<USERNAME>",
"password": "<PASSWORD>"
},
"connectionString": "mysql://<USERNAME>:<PASSWORD>@<HOST>:4000",
"expiresAt": "<ISO_TIMESTAMP>"
}
}
After you receive the response, use instance.connectionString to connect with a MySQL-compatible client or driver.
After provisioning succeeds, you should ask the user:
If the user says yes, run a small bootstrap SQL flow like this:
CREATE TABLE IF NOT EXISTS quickstart_notes (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
title VARCHAR(100) NOT NULL,
content TEXT NOT NULL,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
INSERT INTO quickstart_notes (title, content) VALUES
('welcome', 'TiDB Cloud Zero quickstart row'),
('query-demo', 'Run SELECT * FROM quickstart_notes; to verify data');
SELECT * FROM quickstart_notes ORDER BY id;
mysql --connect-timeout=10 --protocol=TCP -h '<HOST>' -P 4000 -u '<USERNAME>' -p'<PASSWORD>'
mysql2)import mysql from "mysql2/promise";
const response = await createDatabase(); // your API call result
const connectionUrl = new URL(response.instance.connectionString);
connectionUrl.pathname = "/<DATABASE>";
connectionUrl.searchParams.set("ssl", JSON.stringify({ rejectUnauthorized: true }));
const connection = await mysql.createConnection(connectionUrl.toString());
const [rows] = await connection.query("SELECT NOW() AS now_time");
console.log(rows);
await connection.end();