Docs / Concepts
The bucket is the database
One object-store bucket holds everything durable. Nodes are disposable compute that recover from it.
Available View Markdown
# The bucket is the database
> Status: Available. One object-store bucket holds everything durable. Nodes are disposable compute that recover from it.
Gauntlet has one durable component: an S3-compatible bucket. Memory and local disk are caches. A node that dies is replaced by starting another one against the same bucket and prefix.
## What an acknowledgement means
A write is acknowledged only after the bucket holds what recovery needs. This is the default and, today, the only mode. There is no acknowledgement from memory, from a local disk or from a peer.
That has two consequences worth planning for:
- **Losing every node loses nothing.** Start nodes against the same bucket and prefix and the databases are there.
- **Commit latency follows the bucket.** Each commit waits for conditional writes to the bucket. Put the bucket next to the nodes.
A per-database *peer-durable* mode, which would acknowledge on peers and upload afterwards, is designed but not built. Bucket-only stays the default.
## What is in the bucket
- **A journal per shard**, written with create-if-absent. Two writers can never both win the same slot.
- **Ownership barriers** that fence an old owner once a new one takes over.
- **Write-once decision objects** for transactions that span shards.
- **Checkpoints**, so recovery does not replay the whole journal.
- **Leases**, through which nodes discover each other. There is no member list to maintain.
## What a node is
`gauntlet serve` is the only server process. Each node:
- accepts PostgreSQL wire and HTTP connections for **any** database;
- owns some databases' shards at a given moment and routes requests for the others to their owners;
- keeps a bounded, verified block cache on local disk. The cache is rebuilt from the bucket if it is lost.
Normal SQL does not pass through a control plane. There is no control plane in the query path.
## What the bucket must provide
More than the S3 API: atomic create-if-absent (`If-None-Match: *`), read-after-write consistency and a strongly consistent, ordered LIST. `gauntlet qualify` checks this, and every node start runs the same checks. A bucket that fails is refused. See [deploy and qualify a bucket](https://gauntlet-db.stavros.xyz/docs/operations/deploy.md).
The bucket is **trusted**: Gauntlet does not encrypt or sign its objects. Scope the bucket key to that bucket, and never set lifecycle or expiry rules on the prefix.
## Failure, in one table
| Event | What happens |
|---|---|
| One node is killed | The other nodes take over its databases through normal recovery |
| All nodes are lost | Nothing is lost. Start nodes against the same bucket |
| The local cache disk is lost | Nothing is lost. The cache is rebuilt |
| The bucket is unreachable | No node can commit. `/ready` turns 503. More nodes do not help |
No failover time is guaranteed in pre-beta. See [node failure and recovery](https://gauntlet-db.stavros.xyz/docs/operations/failover.md).
## Evidence and its limits
The commit and recovery protocol is checked by fault-injection tests, deterministic simulation and bounded TLA+ models, which gate changes to the engine. These check limited compositions. They are engineering evidence, not an independent audit and not a proof about arbitrary deployments.
---
Source: https://gauntlet-db.stavros.xyz/docs/concepts/architecture
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 has one durable component: an S3-compatible bucket. Memory and local disk are caches. A node that dies is replaced by starting another one against the same bucket and prefix.
#What an acknowledgement means
A write is acknowledged only after the bucket holds what recovery needs. This is the default and, today, the only mode. There is no acknowledgement from memory, from a local disk or from a peer.
That has two consequences worth planning for:
- Losing every node loses nothing. Start nodes against the same bucket and prefix and the databases are there.
- Commit latency follows the bucket. Each commit waits for conditional writes to the bucket. Put the bucket next to the nodes.
A per-database peer-durable mode, which would acknowledge on peers and upload afterwards, is designed but not built. Bucket-only stays the default.
#What is in the bucket
- A journal per shard, written with create-if-absent. Two writers can never both win the same slot.
- Ownership barriers that fence an old owner once a new one takes over.
- Write-once decision objects for transactions that span shards.
- Checkpoints, so recovery does not replay the whole journal.
- Leases, through which nodes discover each other. There is no member list to maintain.
#What a node is
gauntlet serve is the only server process. Each node:
- accepts PostgreSQL wire and HTTP connections for any database;
- owns some databases' shards at a given moment and routes requests for the others to their owners;
- keeps a bounded, verified block cache on local disk. The cache is rebuilt from the bucket if it is lost.
Normal SQL does not pass through a control plane. There is no control plane in the query path.
#What the bucket must provide
More than the S3 API: atomic create-if-absent (If-None-Match: *), read-after-write consistency and a strongly consistent, ordered LIST. gauntlet qualify checks this, and every node start runs the same checks. A bucket that fails is refused. See deploy and qualify a bucket.
The bucket is trusted: Gauntlet does not encrypt or sign its objects. Scope the bucket key to that bucket, and never set lifecycle or expiry rules on the prefix.
#Failure, in one table
| Event | What happens |
|---|---|
| One node is killed | The other nodes take over its databases through normal recovery |
| All nodes are lost | Nothing is lost. Start nodes against the same bucket |
| The local cache disk is lost | Nothing is lost. The cache is rebuilt |
| The bucket is unreachable | No node can commit. /ready turns 503. More nodes do not help |
No failover time is guaranteed in pre-beta. See node failure and recovery.
#Evidence and its limits
The commit and recovery protocol is checked by fault-injection tests, deterministic simulation and bounded TLA+ models, which gate changes to the engine. These check limited compositions. They are engineering evidence, not an independent audit and not a proof about arbitrary deployments.