Docs / Concepts
Databases, identity and tokens
A database has a name, an immutable ID and one token. The database is the unit of isolation.
Available View Markdown
# Databases, identity and tokens
> Status: Available. A database has a name, an immutable ID and one token. The database is the unit of isolation.
## Name and ID
`gauntlet admin create-database app` reserves an **immutable ID** and gives the database the name `app`. Clients use the name: it is the `dbname` on PostgreSQL wire and the path segment in `/db/<name>/…` over HTTP.
Keep the JSON that `create-database` prints. If the command reports an unknown outcome, retry with `--reservation <file>`, never by name: a retry by name reserves a second ID.
`gauntlet admin drop-database app --id <id>` drops one exact ID. Its data is not reclaimed in pre-beta.
## One token per database
Each database has exactly one token.
- It is derived from the deployment's client token and the database's ID. `gauntlet admin token app` computes it locally.
- It is the PostgreSQL password (for any user name) and the HTTP bearer token.
- Anyone who holds it can do everything in that database. There are no SQL roles and no table privileges.
| Token | Scope |
|---|---|
| Database token | One database. Hand this to applications and agents |
| Client token | The whole deployment's client access: every database token is derived from it. Guard it like the admin token |
| Peer token | Node-to-node authentication, with certificates |
| Admin token | `/admin`, `/status` and `/metrics` |
## The database is the boundary
Clients of different databases are mutually untrusted. A token is bound to one immutable ID and cannot open another database.
This is why Gauntlet suits **one database per agent, per user or per tenant**: isolation is a property of the boundary, not of row-level rules you have to get right. Idle databases are released and cost only their stored bytes ([scale to zero](https://gauntlet-db.stavros.xyz/docs/concepts/scale-to-zero.md)).
What the project has shown is a deployment with 1,000 databases. A fleet of that size works today; qualification at 100,000 and one million is [planned](https://gauntlet-db.stavros.xyz/docs/roadmap.md).
## Today's limits
- **One shard per new database.** One database is limited to what one shard owner can serve. Shard split and move are not built.
- **No listing with labels or paging.** `gauntlet admin list` is a flat list. Labels for agent, tenant and environment, and a paged listing that never activates a database, are planned.
- **Creation needs the admin token.** Scoped creation inside a project is planned.
## Coming
- **Read-only tokens** and **short-lived tokens**.
- **Tenant scopes**: create, list and drop inside a scope, with per-scope limits.
- **A fleet listing** with labels, filters and paging, read from usage rows so that listing never wakes a database.
---
Source: https://gauntlet-db.stavros.xyz/docs/concepts/databases
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.#Name and ID
gauntlet admin create-database app reserves an immutable ID and gives the database the name app. Clients use the name: it is the dbname on PostgreSQL wire and the path segment in /db/<name>/… over HTTP.
Keep the JSON that create-database prints. If the command reports an unknown outcome, retry with --reservation <file>, never by name: a retry by name reserves a second ID.
gauntlet admin drop-database app --id <id> drops one exact ID. Its data is not reclaimed in pre-beta.
#One token per database
Each database has exactly one token.
- It is derived from the deployment's client token and the database's ID.
gauntlet admin token appcomputes it locally. - It is the PostgreSQL password (for any user name) and the HTTP bearer token.
- Anyone who holds it can do everything in that database. There are no SQL roles and no table privileges.
| Token | Scope |
|---|---|
| Database token | One database. Hand this to applications and agents |
| Client token | The whole deployment's client access: every database token is derived from it. Guard it like the admin token |
| Peer token | Node-to-node authentication, with certificates |
| Admin token | /admin, /status and /metrics |
#The database is the boundary
Clients of different databases are mutually untrusted. A token is bound to one immutable ID and cannot open another database.
This is why Gauntlet suits one database per agent, per user or per tenant: isolation is a property of the boundary, not of row-level rules you have to get right. Idle databases are released and cost only their stored bytes (scale to zero).
What the project has shown is a deployment with 1,000 databases. A fleet of that size works today; qualification at 100,000 and one million is planned.
#Today's limits
- One shard per new database. One database is limited to what one shard owner can serve. Shard split and move are not built.
- No listing with labels or paging.
gauntlet admin listis a flat list. Labels for agent, tenant and environment, and a paged listing that never activates a database, are planned. - Creation needs the admin token. Scoped creation inside a project is planned.
#Coming
- Read-only tokens and short-lived tokens.
- Tenant scopes: create, list and drop inside a scope, with per-scope limits.
- A fleet listing with labels, filters and paging, read from usage rows so that listing never wakes a database.