Docs / Get started
Gauntlet documentation
Gauntlet is a distributed SQL database whose only durable store is one object-store bucket. These pages cover what works today, what is refused, and what is coming.
Pre-beta View Markdown
# Gauntlet documentation
> Status: Pre-beta. Gauntlet is a distributed SQL database whose only durable store is one object-store bucket. These pages cover what works today, what is refused, and what is coming.
Gauntlet is a distributed SQL database. Its only durable store is one S3-compatible bucket. Nodes hold nothing you cannot lose: memory and local disk are caches, and a node that dies is replaced by starting another one against the same bucket.
> **Pre-beta.** Gauntlet is pre-release software. Its own beta acceptance run (three hosts, node kills, 48–72 hours of load and a restore drill) has not passed yet. There is no public download; builds go to invited testers. [Join the waitlist](https://gauntlet-db.stavros.xyz/start) to be told when that changes.
## The short version
- **Transactions are strictly serializable**, including transactions that span shards. A write is acknowledged only after the bucket holds what recovery needs.
- **SQL is the SQLite family.** The engine is Turso. It is not PostgreSQL SQL.
- **Clients connect over the PostgreSQL wire protocol** (psql, psycopg, node-postgres, pgjdbc) or over an HTTP JSON API.
- **One process type.** `gauntlet serve` runs on each host and serves many named databases. Nodes find each other through leases in the bucket.
- **Idle databases cost only their bytes.** A released database makes no bucket requests until its next query.
## Start here
| Page | Use it to |
|---|---|
| [Quickstart](https://gauntlet-db.stavros.xyz/docs/quickstart.md) | Run one node, then three nodes on one bucket, and connect a client |
| [Connect an agent](https://gauntlet-db.stavros.xyz/docs/agents.md) | Hand a coding agent an accurate, secret-free prompt |
| [Transactions](https://gauntlet-db.stavros.xyz/docs/concepts/transactions.md) | Learn the guarantee and the two error codes every client must handle |
| [SQL compatibility](https://gauntlet-db.stavros.xyz/docs/sql/compatibility.md) | See which SQL works and what is refused |
| [Limits](https://gauntlet-db.stavros.xyz/docs/limits.md) | Know what pre-beta Gauntlet does not do before you rely on it |
## Who it fits today
It fits you if all of these are true:
- You can run three Linux x86_64 hosts and one bucket, and you are comfortable with TLS certificates, systemd or Docker, and Prometheus.
- Your data can be reloaded or restored from your own backup. There is no in-place upgrade from the beta to v1.
- Your application can retry a transaction on `40001` and can handle an unknown commit outcome (`40003`).
- A SQLite-style dialect is acceptable, and you do not need PostgreSQL catalogs, extensions or an ORM's introspection queries.
It does not fit you if you need any of these today: production guarantees, PostgreSQL SQL, `ALTER TABLE` or `CREATE INDEX`, point-in-time restore, per-user roles, or storage that shrinks when you delete data. Most of those are on the [roadmap](https://gauntlet-db.stavros.xyz/docs/roadmap.md).
## For agents and tooling
Every page has a **Copy as Markdown** button and a raw Markdown URL (add `.md` to the page's address). The whole documentation is indexed at [/llms.txt](https://gauntlet-db.stavros.xyz/llms.txt) and concatenated at [/llms-full.txt](https://gauntlet-db.stavros.xyz/llms-full.txt). Both are generated from the same files as these pages.
---
Source: https://gauntlet-db.stavros.xyz/docs
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.Gauntlet is a distributed SQL database. Its only durable store is one S3-compatible bucket. Nodes hold nothing you cannot lose: memory and local disk are caches, and a node that dies is replaced by starting another one against the same bucket.
Pre-beta. Gauntlet is pre-release software. Its own beta acceptance run (three hosts, node kills, 48–72 hours of load and a restore drill) has not passed yet. There is no public download; builds go to invited testers. Join the waitlist to be told when that changes.
#The short version
- Transactions are strictly serializable, including transactions that span shards. A write is acknowledged only after the bucket holds what recovery needs.
- SQL is the SQLite family. The engine is Turso. It is not PostgreSQL SQL.
- Clients connect over the PostgreSQL wire protocol (psql, psycopg, node-postgres, pgjdbc) or over an HTTP JSON API.
- One process type.
gauntlet serveruns on each host and serves many named databases. Nodes find each other through leases in the bucket. - Idle databases cost only their bytes. A released database makes no bucket requests until its next query.
#Start here
| Page | Use it to |
|---|---|
| Quickstart | Run one node, then three nodes on one bucket, and connect a client |
| Connect an agent | Hand a coding agent an accurate, secret-free prompt |
| Transactions | Learn the guarantee and the two error codes every client must handle |
| SQL compatibility | See which SQL works and what is refused |
| Limits | Know what pre-beta Gauntlet does not do before you rely on it |
#Who it fits today
It fits you if all of these are true:
- You can run three Linux x86_64 hosts and one bucket, and you are comfortable with TLS certificates, systemd or Docker, and Prometheus.
- Your data can be reloaded or restored from your own backup. There is no in-place upgrade from the beta to v1.
- Your application can retry a transaction on
40001and can handle an unknown commit outcome (40003). - A SQLite-style dialect is acceptable, and you do not need PostgreSQL catalogs, extensions or an ORM's introspection queries.
It does not fit you if you need any of these today: production guarantees, PostgreSQL SQL, ALTER TABLE or CREATE INDEX, point-in-time restore, per-user roles, or storage that shrinks when you delete data. Most of those are on the roadmap.
#For agents and tooling
Every page has a Copy as Markdown button and a raw Markdown URL (add .md to the page's address). The whole documentation is indexed at /llms.txt and concatenated at /llms-full.txt. Both are generated from the same files as these pages.