# Databases, identity and tokens

> Status: Available. A database has a name, an immutable ID and one token. The database is the unit of isolation.

## Name and ID

`gauntlet admin create-database app` reserves an **immutable ID** and gives the database the name `app`. Clients use the name: it is the `dbname` on PostgreSQL wire and the path segment in `/db/<name>/…` over HTTP.

Keep the JSON that `create-database` prints. If the command reports an unknown outcome, retry with `--reservation <file>`, never by name: a retry by name reserves a second ID.

`gauntlet admin drop-database app --id <id>` drops one exact ID. Its data is not reclaimed in pre-beta.

## One token per database

Each database has exactly one token.

- It is derived from the deployment's client token and the database's ID. `gauntlet admin token app` computes it locally.
- It is the PostgreSQL password (for any user name) and the HTTP bearer token.
- Anyone who holds it can do everything in that database. There are no SQL roles and no table privileges.

| Token | Scope |
|---|---|
| Database token | One database. Hand this to applications and agents |
| Client token | The whole deployment's client access: every database token is derived from it. Guard it like the admin token |
| Peer token | Node-to-node authentication, with certificates |
| Admin token | `/admin`, `/status` and `/metrics` |

## The database is the boundary

Clients of different databases are mutually untrusted. A token is bound to one immutable ID and cannot open another database.

This is why Gauntlet suits **one database per agent, per user or per tenant**: isolation is a property of the boundary, not of row-level rules you have to get right. Idle databases are released and cost only their stored bytes ([scale to zero](https://gauntlet-db.stavros.xyz/docs/concepts/scale-to-zero.md)).

What the project has shown is a deployment with 1,000 databases. A fleet of that size works today; qualification at 100,000 and one million is [planned](https://gauntlet-db.stavros.xyz/docs/roadmap.md).

## Today's limits

- **One shard per new database.** One database is limited to what one shard owner can serve. Shard split and move are not built.
- **No listing with labels or paging.** `gauntlet admin list` is a flat list. Labels for agent, tenant and environment, and a paged listing that never activates a database, are planned.
- **Creation needs the admin token.** Scoped creation inside a project is planned.

## Coming

- **Read-only tokens** and **short-lived tokens**.
- **Tenant scopes**: create, list and drop inside a scope, with per-scope limits.
- **A fleet listing** with labels, filters and paging, read from usage rows so that listing never wakes a database.

---
Source: https://gauntlet-db.stavros.xyz/docs/concepts/databases