Docs / Clients
HTTP JSON API
Run a statement, an atomic batch or an interactive session over HTTPS with a bearer token.
Available View Markdown
# HTTP JSON API
> Status: Available. Run a statement, an atomic batch or an interactive session over HTTPS with a bearer token.
| | |
|---|---|
| **Works** | POST /db/<name>/sql, POST /db/<name>/tx for an atomic list of statements, interactive sessions, GET /db/<name>/txn/<txid> for outcome lookup, GET /db/<name>/ready. |
| **Differs** | This is Gauntlet's own JSON shape. It is not the libSQL (Hrana) protocol. |
| **Missing** | A published OpenAPI schema, a libSQL-compatible endpoint, CORS for browsers. |
| **Operational impact** | /sql, /tx and sessions activate the database. /ready does not. HTTP requests are not counted against the PostgreSQL connection limit. |
| **Evidence** | Covered by the project's gateway tests. The request and response shapes may still change in pre-beta. |
All routes are under `/db/<name>/` on any node's HTTP listener (port 7101 in the examples). Send the [database token](https://gauntlet-db.stavros.xyz/docs/concepts/databases.md) as a bearer token over TLS.
## One statement
```sh
curl --cacert ca/ca.crt \
-H "Authorization: Bearer $GAUNTLET_DATABASE_TOKEN" \
-H 'Content-Type: application/json' \
https://n3.example.net:7101/db/app/sql \
-d '{"sql": "SELECT name FROM items WHERE id = $1", "params": [1]}'
```
The body is `{"sql": "…", "params": […]}`; `params` is optional. A result has `columns`, `rows` (an array of arrays) and `rows_affected`.
## An atomic batch
`/tx` runs a list of statements as one transaction. Either all commit or none do.
```sh
curl --cacert ca/ca.crt \
-H "Authorization: Bearer $GAUNTLET_DATABASE_TOKEN" \
-H 'Content-Type: application/json' \
https://n3.example.net:7101/db/app/tx \
-d '{"statements": [
{"sql": "UPDATE accounts SET balance = balance - 5 WHERE id = $1", "params": [1]},
{"sql": "UPDATE accounts SET balance = balance + 5 WHERE id = $1", "params": [2]}
]}'
```
The response has one entry in `results` per statement.
## Sessions
`POST /db/<name>/session` opens an interactive session and returns its ID; pass `"session": <id>` in later `/sql` bodies to run `BEGIN … COMMIT` across requests. `DELETE /db/<name>/session/<id>` closes it. Prefer `/tx` when the statements are known up front: it has no session to leak.
## Errors
An error is a JSON body with an `error` object that carries the same SQLSTATE code as PostgreSQL wire.
| SQLSTATE | HTTP status | Do |
|---|---|---|
| `40001` | 409 | Retry the whole transaction |
| `57P03` | 503 | Retry with backoff |
| `40003` | 504 | [Look the outcome up](https://gauntlet-db.stavros.xyz/docs/concepts/transactions.md#40003-the-commit-outcome-is-unknown). Do not retry |
| `XX…` | 500 | Report it |
| Any other | 400 | Fix the request |
## Outcome lookup
```sh
curl --cacert ca/ca.crt -H "Authorization: Bearer $GAUNTLET_DATABASE_TOKEN" \
https://n1.example.net:7101/db/app/txn/<txid>
```
Returns `{"txid": "…", "status": "committed" | "aborted" | "unknown" | "quarantined"}`, or HTTP 503 with `lookup_failed`.
## Readiness without waking
`GET /db/<name>/ready` with the database token reports that database's readiness **without activating it**. Use it for health checks; never use `SELECT 1` for a fleet-wide probe.
## Values
Integers and floats are JSON numbers, text is a string, a BLOB is `{"$blob": "<hex>"}`, and infinite floats are `{"$float": "Infinity"}` or `{"$float": "-Infinity"}`.
## The CLI
```sh
GAUNTLET_CLIENT_TOKEN=$TOKEN gauntlet sql --url https://n3.example.net:7101/db/app 'SELECT * FROM items'
```
---
Source: https://gauntlet-db.stavros.xyz/docs/clients/http
Connect this project to my existing Gauntlet database.
Context:
- Documentation index for agents: https://gauntlet-db.stavros.xyz/llms.txt
- Quickstart: https://gauntlet-db.stavros.xyz/docs/quickstart.md
- SQL compatibility and error codes: https://gauntlet-db.stavros.xyz/docs/sql/compatibility.md
- Database: the one already configured for this project
- Protocol: PostgreSQL wire or the native HTTP JSON API, whichever this project already uses
- Connection values are in environment variables: GAUNTLET_DATABASE_URL (PostgreSQL wire),
GAUNTLET_HTTP_URL (HTTP base URL) and GAUNTLET_DATABASE_TOKEN (the database token).
These names are a convention, not a shipped SDK setting. Keep this project's own names if it has them.
Before editing, read the Gauntlet documentation above and inspect how this project
already talks to its database. Gauntlet is pre-beta software; where the documentation
and my deployment disagree, tell me instead of guessing.
What Gauntlet is:
- A distributed SQL database. SQL is the SQLite family, run by the Turso engine.
- The PostgreSQL wire protocol is a transport only. There is no PostgreSQL SQL dialect,
no pg_catalog or information_schema, no extensions, and no ORM is certified yet.
- libSQL client compatibility is not available yet. Do not assume it.
Connecting:
- PostgreSQL wire: dbname is the database name, the user name is ignored, and the
password is the database token. Authentication is SCRAM-SHA-256. Keep TLS
verification on (sslmode=verify-full with the deployment's CA certificate).
- HTTP: POST <GAUNTLET_HTTP_URL>/db/<name>/sql with a JSON body
{"sql": "...", "params": [...]} and the header "Authorization: Bearer <token>".
POST /db/<name>/tx runs a list of statements atomically.
SQL rules that differ from PostgreSQL:
- Every table needs an explicit primary key, and INSERT supplies the key value.
- CREATE TABLE is a standalone statement outside a transaction. There is no ALTER TABLE,
DROP TABLE or CREATE INDEX; an index comes only from a UNIQUE constraint at creation.
- Parameters are $1, ?1 or ?. Names are single-part (no schema.table).
- Column types follow SQLite affinity. In prepared statements ordinary columns are
described as text; CAST(x AS INTEGER) when the driver needs a number.
Errors you must handle (SQLSTATE):
- 40001: conflict. Roll back and retry the whole transaction. Locking is no-wait, so
this is normal under contention.
- 40003: commit outcome unknown. Do NOT retry. Look the transaction up with
GET /db/<name>/txn/<txid> and replay only if the status is `aborted`.
- 57P03: cannot serve right now. Roll back, then retry the whole transaction with backoff.
- 53300: too many connections. Back off; keep the pool below the node's limit.
Credentials and scope:
- Use only the database token for this one database. Keep it server-side and out of
source, logs, browser bundles and this conversation.
- Never use or ask for a deployment admin token, a client token or bucket credentials.
- Do not create, drop, back up, restore or branch databases, and do not rotate credentials.
Task:
1. Add the smallest connection integration that fits this project.
2. Run one explicit `SELECT 1` connectivity check. It may activate this database if it
is idle; do not probe or wake any other database.
3. Do not change the schema or write application data unless I ask for it.
Report the files changed, the protocol and client used, the result of the check, and
anything this project needs that Gauntlet does not support.- Works
- POST /db/
/sql, POST /db/ /tx for an atomic list of statements, interactive sessions, GET /db/ /txn/ for outcome lookup, GET /db/ /ready. - Differs
- This is Gauntlet's own JSON shape. It is not the libSQL (Hrana) protocol.
- Missing
- A published OpenAPI schema, a libSQL-compatible endpoint, CORS for browsers.
- Operational impact
- /sql, /tx and sessions activate the database. /ready does not. HTTP requests are not counted against the PostgreSQL connection limit.
- Evidence
- Covered by the project's gateway tests. The request and response shapes may still change in pre-beta.
All routes are under /db/<name>/ on any node's HTTP listener (port 7101 in the examples). Send the database token as a bearer token over TLS.
#One statement
Shell
curl --cacert ca/ca.crt \
-H "Authorization: Bearer $GAUNTLET_DATABASE_TOKEN" \
-H 'Content-Type: application/json' \
https://n3.example.net:7101/db/app/sql \
-d '{"sql": "SELECT name FROM items WHERE id = $1", "params": [1]}'The body is {"sql": "…", "params": […]}; params is optional. A result has columns, rows (an array of arrays) and rows_affected.
#An atomic batch
/tx runs a list of statements as one transaction. Either all commit or none do.
Shell
curl --cacert ca/ca.crt \
-H "Authorization: Bearer $GAUNTLET_DATABASE_TOKEN" \
-H 'Content-Type: application/json' \
https://n3.example.net:7101/db/app/tx \
-d '{"statements": [
{"sql": "UPDATE accounts SET balance = balance - 5 WHERE id = $1", "params": [1]},
{"sql": "UPDATE accounts SET balance = balance + 5 WHERE id = $1", "params": [2]}
]}'The response has one entry in results per statement.
#Sessions
POST /db/<name>/session opens an interactive session and returns its ID; pass "session": <id> in later /sql bodies to run BEGIN … COMMIT across requests. DELETE /db/<name>/session/<id> closes it. Prefer /tx when the statements are known up front: it has no session to leak.
#Errors
An error is a JSON body with an error object that carries the same SQLSTATE code as PostgreSQL wire.
| SQLSTATE | HTTP status | Do |
|---|---|---|
40001 |
409 | Retry the whole transaction |
57P03 |
503 | Retry with backoff |
40003 |
504 | Look the outcome up. Do not retry |
XX… |
500 | Report it |
| Any other | 400 | Fix the request |
#Outcome lookup
Shell
curl --cacert ca/ca.crt -H "Authorization: Bearer $GAUNTLET_DATABASE_TOKEN" \
https://n1.example.net:7101/db/app/txn/<txid>Returns {"txid": "…", "status": "committed" | "aborted" | "unknown" | "quarantined"}, or HTTP 503 with lookup_failed.
#Readiness without waking
GET /db/<name>/ready with the database token reports that database's readiness without activating it. Use it for health checks; never use SELECT 1 for a fleet-wide probe.
#Values
Integers and floats are JSON numbers, text is a string, a BLOB is {"$blob": "<hex>"}, and infinite floats are {"$float": "Infinity"} or {"$float": "-Infinity"}.
#The CLI
Shell
GAUNTLET_CLIENT_TOKEN=$TOKEN gauntlet sql --url https://n3.example.net:7101/db/app 'SELECT * FROM items'