Docs / Operations
Deploy and qualify a bucket
What a deployment is, what the bucket must guarantee, and how nodes are secured.
Available View Markdown
# Deploy and qualify a bucket
> Status: Available. What a deployment is, what the bucket must guarantee, and how nodes are secured.
A deployment is one bucket prefix and the `gauntlet serve` nodes that point at it. The supported shape in pre-beta is `gauntlet serve` on Linux x86_64 (glibc 2.34 or newer), from a systemd unit or the container image.
One rule comes first: **the bucket is the database.** Never delete, expire or edit objects under the deployment's prefix, and never set a lifecycle rule on it.
## Qualify the bucket
Gauntlet needs atomic create-if-absent (`If-None-Match: *`), read-after-write consistency and a strongly consistent, ordered LIST. An S3-compatible endpoint alone is not enough.
```sh
(set -a; . ./secrets.env; gauntlet qualify --store 's3:#qualify-check')
```
`gauntlet qualify` exits 0 on a pass, 2 when a check fails and 3 when the result is inconclusive. Every node start runs the same checks. Never run `qualify` against a live prefix.
| Provider | Status |
|---|---|
| Tigris | Run by the project |
| Cloudflare R2 | Run by the project. Slower conditional writes in those runs |
| AWS S3 | Unverified. No recorded run |
| Google Cloud Storage | Unverified. Qualification is planned |
| MinIO | Unverified. No recorded run |
One strongly consistent, **single-region** bucket is the only supported shape. A multi-region or eventually consistent bucket is not safe as the only arbiter.
## Bucket settings
| Variable | Default | Meaning |
|---|---|---|
| `GAUNTLET_S3_ENDPOINT` | required | The service URL |
| `GAUNTLET_S3_BUCKET` | required | The bucket name |
| `GAUNTLET_S3_ACCESS_KEY_ID`, `GAUNTLET_S3_SECRET_ACCESS_KEY` | required | A key that can read and write this bucket only |
| `GAUNTLET_S3_REGION` | `auto` | The signing region |
| `GAUNTLET_S3_PATH_STYLE` | `true` | Set `false` for virtual-hosted bucket addressing |
| `GAUNTLET_S3_TIMEOUT_MS` | `10000` | Deadline for one control request |
## Security
- **TLS on every listener.** A listener that is not on loopback must use TLS, or the node refuses to start. The deployment has its own private CA; each node's certificate is both its server certificate and its client certificate to the other nodes.
- **SCRAM-SHA-256** for PostgreSQL clients. One token per database; a separate admin token.
- **Tokens are at least 32 characters** and never go in the config file. Each can come from a file named by `GAUNTLET_<NAME>_FILE`.
- **No SQL roles** or table privileges.
- **The bucket is trusted.** Objects are not encrypted or signed by Gauntlet.
A node refuses to start, before it binds or writes anything, if TLS is half configured, the key file is readable by others, the certificate does not cover the advertised name, a token is missing or short, or the bucket fails qualification.
## Health endpoints
| Endpoint | Auth | Meaning |
|---|---|---|
| `GET /health` | none | Liveness. Answers `ok` while the process runs |
| `GET /ready` | none | Readiness. 200 when the node can serve; 503 when it cannot |
| `GET /db/<name>/ready` | database token | That database's readiness. Does not wake an idle database |
Point a load balancer's health check at `GET /ready`.
## Configuration
The config file's keys are the flag names of `gauntlet serve --help`. A flag on the command line wins over an option's environment variable, which wins over the file. A misspelt key, a value of the wrong type, or a key that looks like a secret stops the start.
## Coming
Managed Gauntlet Cloud and packaged bring-your-own-cloud installs are designed and not built. Qualification of AWS S3 and Google Cloud Storage is planned.
---
Source: https://gauntlet-db.stavros.xyz/docs/operations/deploy
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.A deployment is one bucket prefix and the gauntlet serve nodes that point at it. The supported shape in pre-beta is gauntlet serve on Linux x86_64 (glibc 2.34 or newer), from a systemd unit or the container image.
One rule comes first: the bucket is the database. Never delete, expire or edit objects under the deployment's prefix, and never set a lifecycle rule on it.
#Qualify the bucket
Gauntlet needs atomic create-if-absent (If-None-Match: *), read-after-write consistency and a strongly consistent, ordered LIST. An S3-compatible endpoint alone is not enough.
Shell
(set -a; . ./secrets.env; gauntlet qualify --store 's3:#qualify-check')gauntlet qualify exits 0 on a pass, 2 when a check fails and 3 when the result is inconclusive. Every node start runs the same checks. Never run qualify against a live prefix.
| Provider | Status |
|---|---|
| Tigris | Run by the project |
| Cloudflare R2 | Run by the project. Slower conditional writes in those runs |
| AWS S3 | Unverified. No recorded run |
| Google Cloud Storage | Unverified. Qualification is planned |
| MinIO | Unverified. No recorded run |
One strongly consistent, single-region bucket is the only supported shape. A multi-region or eventually consistent bucket is not safe as the only arbiter.
#Bucket settings
| Variable | Default | Meaning |
|---|---|---|
GAUNTLET_S3_ENDPOINT |
required | The service URL |
GAUNTLET_S3_BUCKET |
required | The bucket name |
GAUNTLET_S3_ACCESS_KEY_ID, GAUNTLET_S3_SECRET_ACCESS_KEY |
required | A key that can read and write this bucket only |
GAUNTLET_S3_REGION |
auto |
The signing region |
GAUNTLET_S3_PATH_STYLE |
true |
Set false for virtual-hosted bucket addressing |
GAUNTLET_S3_TIMEOUT_MS |
10000 |
Deadline for one control request |
#Security
- TLS on every listener. A listener that is not on loopback must use TLS, or the node refuses to start. The deployment has its own private CA; each node's certificate is both its server certificate and its client certificate to the other nodes.
- SCRAM-SHA-256 for PostgreSQL clients. One token per database; a separate admin token.
- Tokens are at least 32 characters and never go in the config file. Each can come from a file named by
GAUNTLET_<NAME>_FILE. - No SQL roles or table privileges.
- The bucket is trusted. Objects are not encrypted or signed by Gauntlet.
A node refuses to start, before it binds or writes anything, if TLS is half configured, the key file is readable by others, the certificate does not cover the advertised name, a token is missing or short, or the bucket fails qualification.
#Health endpoints
| Endpoint | Auth | Meaning |
|---|---|---|
GET /health |
none | Liveness. Answers ok while the process runs |
GET /ready |
none | Readiness. 200 when the node can serve; 503 when it cannot |
GET /db/<name>/ready |
database token | That database's readiness. Does not wake an idle database |
Point a load balancer's health check at GET /ready.
#Configuration
The config file's keys are the flag names of gauntlet serve --help. A flag on the command line wins over an option's environment variable, which wins over the file. A misspelt key, a value of the wrong type, or a key that looks like a secret stops the start.
#Coming
Managed Gauntlet Cloud and packaged bring-your-own-cloud installs are designed and not built. Qualification of AWS S3 and Google Cloud Storage is planned.