Docs / Reference
Limits and known gaps
What pre-beta Gauntlet does not do. Read this before you rely on it.
Available View Markdown
# Limits and known gaps
> Status: Available. What pre-beta Gauntlet does not do. Read this before you rely on it.
## The ones that change how you use it
| Limit | What it means for you |
|---|---|
| No in-place upgrade to v1 | Plan to move data by backup and restore |
| Coordinated stop between beta builds | An upgrade is one outage. Never run two builds on one bucket prefix |
| Storage only grows | Budget the bucket for every write ever made, not for live rows. Dropping a database frees nothing |
| Backups are whole images | No point-in-time restore. Losing the bucket loses everything since the last finished backup |
| Commit latency follows the bucket | Each commit waits for conditional writes to the bucket. Put the bucket next to the nodes |
| One token per database, no roles | Anyone with the token can do everything in that database |
| One shard per new database | One database is limited to what one shard owner can serve |
| The bucket is trusted | Gauntlet does not encrypt or sign objects. Scope the bucket key to this bucket |
| No-wait locking | A conflicting transaction gets `40001` and must retry |
| `CREATE TABLE` only | No `ALTER`, `DROP` or `CREATE INDEX` |
| 128 PostgreSQL connections per node by default | One past the limit gets `FATAL 53300` |
| Memory budget is not an RSS ceiling | Size the host above `memory-mib` |
| Slow restart with the same node ID | A node restarted with the same `id` is not ready for 17–18 s |
## Not supported in pre-beta
| Area | Not available |
|---|---|
| Upgrades | No rolling upgrade and no mixed builds |
| Schema changes | No `ALTER`, `DROP` or `CREATE INDEX`. Indexes come only from `UNIQUE` at `CREATE TABLE` |
| SQL features | No savepoints, `COPY`, `SHOW <setting>`, query cancel, named parameters or schema-qualified names |
| Access control | No SQL roles or table privileges. No read-only or short-lived tokens |
| Storage | Nothing is reclaimed. The bucket only grows, even after a database is dropped |
| Recovery | No point-in-time restore. No branches |
| Scaling | One shard per new database. No shard split or move |
| Regions | One deployment, one single-region bucket. No region moves that keep the ID and token. No multi-region writes |
| Platforms | No macOS or Windows server binary. An aarch64 build exists but has not been run as a deployment |
| Clients | No certified ORM. No libSQL-compatible endpoint. No SDK, MCP server or agent skill |
| Service | No managed cloud, no public download, no SLA |
## Not yet verified
These are stated plainly so you do not assume more than has been shown.
- **The beta acceptance run has not passed.** The 48–72 hour run with node kills and a restore drill exists as a test driver.
- **No performance figure applies to the build you receive.** Latency figures the project has recorded come from earlier commits. Measure your own workload.
- **No failover time is guaranteed.**
- **No maximum database count has been qualified above 1,000.**
- **AWS S3, Google Cloud Storage and MinIO have no recorded run.** Only Tigris and Cloudflare R2 appear in the project's results.
- **node-postgres and pgjdbc over TLS** are documented, but the client suites run them on loopback without TLS.
## Where Gauntlet is behind
Product surface, by years: a table cannot change, an index exists only as `UNIQUE`, keys are not generated, no ORM is certified, nothing deletes, and there are no users or roles. Databases that acknowledge on local disks are faster per write than one that waits for a bucket. The [roadmap](https://gauntlet-db.stavros.xyz/docs/roadmap.md) is the plan to close the surface gap; an optional peer-durable mode is the answer to latency.
---
Source: https://gauntlet-db.stavros.xyz/docs/limits
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.#The ones that change how you use it
| Limit | What it means for you |
|---|---|
| No in-place upgrade to v1 | Plan to move data by backup and restore |
| Coordinated stop between beta builds | An upgrade is one outage. Never run two builds on one bucket prefix |
| Storage only grows | Budget the bucket for every write ever made, not for live rows. Dropping a database frees nothing |
| Backups are whole images | No point-in-time restore. Losing the bucket loses everything since the last finished backup |
| Commit latency follows the bucket | Each commit waits for conditional writes to the bucket. Put the bucket next to the nodes |
| One token per database, no roles | Anyone with the token can do everything in that database |
| One shard per new database | One database is limited to what one shard owner can serve |
| The bucket is trusted | Gauntlet does not encrypt or sign objects. Scope the bucket key to this bucket |
| No-wait locking | A conflicting transaction gets 40001 and must retry |
CREATE TABLE only |
No ALTER, DROP or CREATE INDEX |
| 128 PostgreSQL connections per node by default | One past the limit gets FATAL 53300 |
| Memory budget is not an RSS ceiling | Size the host above memory-mib |
| Slow restart with the same node ID | A node restarted with the same id is not ready for 17–18 s |
#Not supported in pre-beta
| Area | Not available |
|---|---|
| Upgrades | No rolling upgrade and no mixed builds |
| Schema changes | No ALTER, DROP or CREATE INDEX. Indexes come only from UNIQUE at CREATE TABLE |
| SQL features | No savepoints, COPY, SHOW <setting>, query cancel, named parameters or schema-qualified names |
| Access control | No SQL roles or table privileges. No read-only or short-lived tokens |
| Storage | Nothing is reclaimed. The bucket only grows, even after a database is dropped |
| Recovery | No point-in-time restore. No branches |
| Scaling | One shard per new database. No shard split or move |
| Regions | One deployment, one single-region bucket. No region moves that keep the ID and token. No multi-region writes |
| Platforms | No macOS or Windows server binary. An aarch64 build exists but has not been run as a deployment |
| Clients | No certified ORM. No libSQL-compatible endpoint. No SDK, MCP server or agent skill |
| Service | No managed cloud, no public download, no SLA |
#Not yet verified
These are stated plainly so you do not assume more than has been shown.
- The beta acceptance run has not passed. The 48–72 hour run with node kills and a restore drill exists as a test driver.
- No performance figure applies to the build you receive. Latency figures the project has recorded come from earlier commits. Measure your own workload.
- No failover time is guaranteed.
- No maximum database count has been qualified above 1,000.
- AWS S3, Google Cloud Storage and MinIO have no recorded run. Only Tigris and Cloudflare R2 appear in the project's results.
- node-postgres and pgjdbc over TLS are documented, but the client suites run them on loopback without TLS.
#Where Gauntlet is behind
Product surface, by years: a table cannot change, an index exists only as UNIQUE, keys are not generated, no ORM is certified, nothing deletes, and there are no users or roles. Databases that acknowledge on local disks are faster per write than one that waits for a bucket. The roadmap is the plan to close the surface gap; an optional peer-durable mode is the answer to latency.