# Quickstart

This skill bypasses `@tidbcloud/serverless` and sends HTTP requests directly to:

- `https://http-<host>/v1beta/sql`

## 0) Set DATABASE_URL

```bash
export DATABASE_URL="mysql://<username>:<password>@<host>/<database>"
```

Example:

```bash
export DATABASE_URL="mysql://4FriSs61wM5o1zu.root:ZwuR6cdSNdjpxEY8@gateway01.us-east-1.dev.shared.aws.tidbcloud.com/test"
```

Or create `.env` in repo root (script auto-loads it):

```bash
DATABASE_URL="mysql://<username>:<password>@<host>/<database>"
```

## 1) Stateless query

```bash
bash skills/tidbcloud-http/scripts/tidb_serverless_http.sh stateless --sql "select 1"
```

Decode behavior for binary-like fields:

- Script checks response types and auto-decodes `BLOB`/`BINARY`/`BIT` values in-memory.
- No second SQL request is made.

## 2) Stateful session (open -> query -> close)

```bash
bash skills/tidbcloud-http/scripts/tidb_serverless_http.sh stateful open
bash skills/tidbcloud-http/scripts/tidb_serverless_http.sh stateful query --sql "use mysql"
bash skills/tidbcloud-http/scripts/tidb_serverless_http.sh stateful query --sql "show tables"
bash skills/tidbcloud-http/scripts/tidb_serverless_http.sh stateful close
```

## 3) Transaction (begin -> query -> commit/rollback)

```bash
bash skills/tidbcloud-http/scripts/tidb_serverless_http.sh tx begin --isolation "READ COMMITTED"
bash skills/tidbcloud-http/scripts/tidb_serverless_http.sh tx query --sql "insert into t values (1)"
bash skills/tidbcloud-http/scripts/tidb_serverless_http.sh tx commit
```

## Notes

- The script persists session tokens under `.session/` by default (`.session/stateless.token`, `.session/stateful.token`, `.session/tx.token`).
- If response returns `TiDB-Session`, the next call reuses it automatically (all modes), including non-2xx cases like `invalid session`.
- If a request returns `invalid session`, script clears the same session file and retries once automatically.
- Use `--session-file <name>` to isolate sessions per task. The file is always created as `.session/<name>`.
- Add `--debug` to print request id and headers summary.
- If `DATABASE_URL` is not found, script prints a setup guide and exits.
- If host cannot be resolved (DNS/host not found), cluster may be on another TiDB Cloud plan. This skill only supports Starter and Essential plans.