Docs / SQL
Error codes
Errors use PostgreSQL SQLSTATE codes on both protocols. Four of them need handling in every client.
Available View Markdown
# Error codes
> Status: Available. Errors use PostgreSQL SQLSTATE codes on both protocols. Four of them need handling in every client.
Over HTTP the same code is in the JSON body under `error`.
## The four you must handle
| Code | Meaning | What to do |
|---|---|---|
| `40001` | Serialization conflict or ownership change | Retry the whole transaction. Locking is no-wait, so this is normal under contention |
| `40003` | Commit outcome unknown | **Do not retry yet.** [Look the transaction up first](https://gauntlet-db.stavros.xyz/docs/concepts/transactions.md#40003-the-commit-outcome-is-unknown) |
| `57P03` | Cannot serve right now | Retry with backoff. Inside a transaction: `ROLLBACK`, then retry the whole transaction |
| `53300` | Too many connections | Back off or use another node. Keep your pool below the node's limit |
### 57P03 in detail
You can see `57P03` when connecting (the node is overloaded, the database could not be activated, or startup took too long), when a node is shutting down, under memory pressure, or when the bucket or a shard owner is unavailable. It is always retryable. Over HTTP it is status 503.
### 53300 in detail
Each node accepts **128 PostgreSQL connections** by default; the operator can change that with `max-connections` (1 to 10000). The count includes connections that are starting up and connections that are idle. One connection past the limit gets `FATAL: sorry, too many clients already`. The limit is per node, so other nodes may have room.
## Other codes
| Code | Meaning |
|---|---|
| `23505` / `23502` | UNIQUE / NOT NULL violation |
| `42P01` / `42703` / `42702` | Unknown table / unknown column / ambiguous column |
| `42P07` / `42P16` | Table already exists / invalid table definition |
| `42601` / `42000` | Syntax error / other planning error |
| `42883` / `42803` | Unknown function or wrong argument count / aggregate used where it is not allowed |
| `0A000` | Feature not supported |
| `25001` | `CREATE TABLE` inside a transaction or mixed with other statements |
| `25006` | Write in a read-only transaction |
| `25P02` | The transaction is aborted; send `ROLLBACK` |
| `25P01` | No transaction is open |
| `54000` | A size limit was exceeded (transaction, value, result, SQL text) |
| `57014` | The statement hit its limit: 20 s or 500 million engine instructions |
| `22003` | Integer or numeric overflow |
| `28P01` | Wrong password (database token) |
| `28000` | Plaintext connection when TLS is required |
| `3D000` | Database does not exist, or was dropped |
| `08P01` | Malformed protocol message or missing parameter |
| `53200` / `53100` | The engine could not allocate memory / storage full |
| `XX000` / `XX001` | Internal error / invalid stored data. Never retried automatically; report it |
## HTTP status mapping
| SQLSTATE | HTTP status |
|---|---|
| `40001` | 409 |
| `57P03` | 503 |
| `40003` | 504 |
| `XX…` | 500 |
| Every other SQL error | 400 |
---
Source: https://gauntlet-db.stavros.xyz/docs/sql/errors
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.Over HTTP the same code is in the JSON body under error.
#The four you must handle
| Code | Meaning | What to do |
|---|---|---|
40001 |
Serialization conflict or ownership change | Retry the whole transaction. Locking is no-wait, so this is normal under contention |
40003 |
Commit outcome unknown | Do not retry yet. Look the transaction up first |
57P03 |
Cannot serve right now | Retry with backoff. Inside a transaction: ROLLBACK, then retry the whole transaction |
53300 |
Too many connections | Back off or use another node. Keep your pool below the node's limit |
#57P03 in detail
You can see 57P03 when connecting (the node is overloaded, the database could not be activated, or startup took too long), when a node is shutting down, under memory pressure, or when the bucket or a shard owner is unavailable. It is always retryable. Over HTTP it is status 503.
#53300 in detail
Each node accepts 128 PostgreSQL connections by default; the operator can change that with max-connections (1 to 10000). The count includes connections that are starting up and connections that are idle. One connection past the limit gets FATAL: sorry, too many clients already. The limit is per node, so other nodes may have room.
#Other codes
| Code | Meaning |
|---|---|
23505 / 23502 |
UNIQUE / NOT NULL violation |
42P01 / 42703 / 42702 |
Unknown table / unknown column / ambiguous column |
42P07 / 42P16 |
Table already exists / invalid table definition |
42601 / 42000 |
Syntax error / other planning error |
42883 / 42803 |
Unknown function or wrong argument count / aggregate used where it is not allowed |
0A000 |
Feature not supported |
25001 |
CREATE TABLE inside a transaction or mixed with other statements |
25006 |
Write in a read-only transaction |
25P02 |
The transaction is aborted; send ROLLBACK |
25P01 |
No transaction is open |
54000 |
A size limit was exceeded (transaction, value, result, SQL text) |
57014 |
The statement hit its limit: 20 s or 500 million engine instructions |
22003 |
Integer or numeric overflow |
28P01 |
Wrong password (database token) |
28000 |
Plaintext connection when TLS is required |
3D000 |
Database does not exist, or was dropped |
08P01 |
Malformed protocol message or missing parameter |
53200 / 53100 |
The engine could not allocate memory / storage full |
XX000 / XX001 |
Internal error / invalid stored data. Never retried automatically; report it |
#HTTP status mapping
| SQLSTATE | HTTP status |
|---|---|
40001 |
409 |
57P03 |
503 |
40003 |
504 |
XX… |
500 |
| Every other SQL error | 400 |