> Fetch the index of every Tonbo docs page as Markdown at https://tonbo.dev/llms.txt

# Manage databases

Last updated 29 October 2026

Create, list, publish and delete databases, and pick their region, whenever your program needs a new one or is done with it: on **Databases** in the console, with the Tonbo CLI, or through the Management API at `https://api.tonbo.dev/v1/databases`. All three act on the same databases.

| Task | Console | CLI | API |
| --- | --- | --- | --- |
| Create | **Create database** | `tonbo database create` | `POST /v1/databases` |
| List | **Databases** | `tonbo database list` | `GET /v1/databases` |
| Show | A database’s name in the list | `tonbo database show` | `GET /v1/databases/{name}` |
| Public or private | **Make public**, **Make private** | `tonbo database update` | `PATCH /v1/databases/{name}` |
| Delete | **Delete database** | `tonbo database delete` | `DELETE /v1/databases/{name}` |

The CLI is `@tonbo/cli`: install it with `npm i -g @tonbo/cli` and sign in with `tonbo login`. The API takes a personal API key, or a token exchanged from a key, as a bearer token (see [API keys and tokens](https://tonbo.dev/docs/platform/api-keys.md)). The examples below keep a key in `TONBO_API_KEY`.

**CLI**

```shell
tonbo database create notes
tonbo database list
tonbo database show notes
tonbo database update notes --public
tonbo database delete notes
```

## Create a database

Any member creates databases. In the console, open **Databases**, choose **Create database**, and give it a name and a region, which cannot be changed later. Through the API, with a key that acts as you and is not narrowed:

```shell
curl -sS https://api.tonbo.dev/v1/databases \
  -H "Authorization: Bearer $TONBO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"notes"}'
```

It answers `201` with the database, its `url` included, once it is active, or `202` while it is still being created: read it again until it is active. A body such as `{"name":"notes","region":"ap-southeast-1"}` names the region (see [Regions and URLs](#regions)). A retry with the same [`Idempotency-Key`](https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/) answers the same database instead of creating a second one; the CLI sends one too and prints it when a creation is not confirmed. An account holds at most 10000 databases, and past that the answer is `403` (see [Limits](https://tonbo.dev/docs/databases/limits.md)). An account whose credit is exhausted answers `402` (see [When the balance runs out](https://tonbo.dev/docs/databases/pricing.md#zero-balance)).

A database can expire, as a stream can: `expires_at` in the body, an RFC 3339 time at least 60 seconds after the creation, the console’s **Expires** choice, or `--expires-at` or `--expires-in` with the CLI (`90s` or more, such as `24h` or `7d`). The expiry is fixed for the database’s life, and Tonbo deletes the database within a minute after it passes, as a deletion would. Without one the database never expires. A retry with the same `Idempotency-Key` must name the same expiry, so the CLI refuses `--expires-in` with `--idempotency-key`: retry with `--expires-at`.

## Regions and URLs

A database lives in one region, fixed when it is created. Every `synced()` waits for a round trip to it, so create a database close to where its program runs. New databases may be created in these regions:

| Region | Location | Database origin | Default |
| --- | --- | --- | --- |
| `us-east-1` | US East (N. Virginia) | `https://db.tonbo.dev` | Yes |
| `ap-southeast-1` | Asia Pacific (Singapore) | `https://streams.ap-southeast-1.tonbo.dev` |  |

Choose the region in the console’s **Create database** form, with `tonbo database create notes --region ap-southeast-1`, or with `region` in the body of `POST https://api.tonbo.dev/v1/databases`. A creation that names no region goes to `us-east-1`. A database’s URL names its region’s origin, your account’s id and its name, and the console, the CLI and the API all show it:

```text
https://db.tonbo.dev/<account-id>/notes
```

Asia Pacific (Singapore) serves databases and streams from one host, so a database URL in `ap-southeast-1` starts with `https://streams.ap-southeast-1.tonbo.dev`. That is by design: the URL is right, and only the path tells a database from a stream.

## Names

1 to 85 lowercase letters, digits, dots, underscores and hyphens, starting and ending with a letter or digit, without `..`, not starting with `m.`, `vol.`, `s.`, `session.` or `proc.` and not `streams` or `new`. A name is unique within the account, in every region, while a database holds it, and is free again once that database is deleted. It cannot be changed, and it appears in the URL as it is.

## States

- `creating`: the database is being created. It cannot be opened yet.
- `active`: the database opens by its URL. Opening a URL never creates a database, so create each one first.
- `deleting`: the database is being deleted.

## List and show

The list shows each database’s name, region, creation date, last write, size and visibility, and to owners and admins its usage this month. A database’s page, `tonbo database show` and `GET /v1/databases/notes` add its URL and state, and its size as log and snapshot. `tonbo database list --prefix` and `?prefix=` list only the names that start with a prefix. The API returns up to 50 databases a page, or `limit`, at most 200, with a `next_cursor` for the next page. A key narrowed to databases lists only the databases it reaches.

## Public and private

A new database is private: reads and writes need a key of the account. A public database is read by anyone with its URL, without a key, and writes still need one. Owners and admins change it, on an active database: **Make public** or **Make private** under **Visibility**, `tonbo database update notes --public` or `--private`, or:

```shell
curl -sS -X PATCH https://api.tonbo.dev/v1/databases/notes \
  -H "Authorization: Bearer $TONBO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"public_read":true}'
```

## Delete a database

Any member deletes databases. Its data is purged from Tonbo and every host’s next open of it fails with `not_found`, leaving the host’s local copy as it is (see [Backups and salvage](https://tonbo.dev/docs/databases/backups.md)). Deletion cannot be undone. The console asks you to type the database’s name, and so does `tonbo database delete` in a terminal; without one it refuses unless `--yes` is given. Through the API:

```shell
curl -sS -X DELETE https://api.tonbo.dev/v1/databases/notes \
  -H "Authorization: Bearer $TONBO_API_KEY"
```

It answers `200` once the database is deleted and `202` while it is being deleted, and repeating it answers the database being deleted. The name is free again once the deletion completes, and the database’s usage this month stays in `tonbo database usage`.