Docs / Concepts
Scale to zero
A database that is not in use is released. While released it makes no bucket requests; its next query activates it.
Available View Markdown
# Scale to zero
> Status: Available. A database that is not in use is released. While released it makes no bucket requests; its next query activates it.
| | |
|---|---|
| **Works** | Release after 30 s without use. Zero bucket requests while released. Activation on the first request. Readiness checks that do not wake a database. |
| **Differs** | The first request after a release is slower, because it activates the database. |
| **Missing** | A published activation latency for your deployment. A qualification above 1,000 databases. |
| **Operational impact** | Listing databases and `GET /db/<name>/ready` do not activate a database. A SQL statement does. A scheduled backup does too. |
| **Evidence** | The project's own run at 1,000 databases. Larger qualifications are planned. |
## What happens
A node serves many named databases. A database that has gone **30 seconds without use** is *released*: its owner writes what it must and lets go. From then on the database makes **no bucket requests**. Its incremental idle footprint is the bytes it already has in the bucket.
The next request for that database *activates* it on some node. That request is slower than the ones after it.
| State | Meaning |
|---|---|
| Released (idle) | No current owner. No bucket requests. Healthy |
| Activating | A node is loading it for a request |
| Serving | A node owns it and answers requests |
A released database is not down. It has no owner because it needs none.
## What does and does not wake a database
| Action | Activates it? |
|---|---|
| A SQL statement over PostgreSQL wire or HTTP | Yes |
| `GET /db/<name>/ready` with the database token | No |
| `gauntlet admin list` | No |
| A scheduled backup | **Yes, today.** Backups that skip idle databases are planned |
This matters for tools: a dashboard or agent that lists a fleet must never run a query per database to do it.
## What "free while idle" does and does not mean
- It means the database's **incremental** cost is its stored bytes: no polling, no heartbeats, no bucket requests.
- It does **not** make a machine you run free, or an allocated node, or the bucket's storage bill.
- Storage only grows in pre-beta. Deleted rows and dropped databases are not reclaimed yet.
## How far this has been shown
The project's own evidence is a run with **1,000 databases** on one deployment. In that run the first query against a released database took about 250 ms at the median. That is one deployment's measurement and not a promise for your hosts and bucket. Measure activation on your own deployment.
Qualifications at 100,000 and at one million databases are planned and have not been run. The bytes and object count of one empty database are not yet published.
---
Source: https://gauntlet-db.stavros.xyz/docs/concepts/scale-to-zero
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.- Works
- Release after 30 s without use. Zero bucket requests while released. Activation on the first request. Readiness checks that do not wake a database.
- Differs
- The first request after a release is slower, because it activates the database.
- Missing
- A published activation latency for your deployment. A qualification above 1,000 databases.
- Operational impact
- Listing databases and
GET /db/<name>/readydo not activate a database. A SQL statement does. A scheduled backup does too. - Evidence
- The project's own run at 1,000 databases. Larger qualifications are planned.
#What happens
A node serves many named databases. A database that has gone 30 seconds without use is released: its owner writes what it must and lets go. From then on the database makes no bucket requests. Its incremental idle footprint is the bytes it already has in the bucket.
The next request for that database activates it on some node. That request is slower than the ones after it.
| State | Meaning |
|---|---|
| Released (idle) | No current owner. No bucket requests. Healthy |
| Activating | A node is loading it for a request |
| Serving | A node owns it and answers requests |
A released database is not down. It has no owner because it needs none.
#What does and does not wake a database
| Action | Activates it? |
|---|---|
| A SQL statement over PostgreSQL wire or HTTP | Yes |
GET /db/<name>/ready with the database token |
No |
gauntlet admin list |
No |
| A scheduled backup | Yes, today. Backups that skip idle databases are planned |
This matters for tools: a dashboard or agent that lists a fleet must never run a query per database to do it.
#What "free while idle" does and does not mean
- It means the database's incremental cost is its stored bytes: no polling, no heartbeats, no bucket requests.
- It does not make a machine you run free, or an allocated node, or the bucket's storage bill.
- Storage only grows in pre-beta. Deleted rows and dropped databases are not reclaimed yet.
#How far this has been shown
The project's own evidence is a run with 1,000 databases on one deployment. In that run the first query against a released database took about 250 ms at the median. That is one deployment's measurement and not a promise for your hosts and bucket. Measure activation on your own deployment.
Qualifications at 100,000 and at one million databases are planned and have not been run. The bytes and object count of one empty database are not yet published.