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.

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). The examples below keep a key in TONBO_API_KEY.

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:

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). A retry with the same Idempotency-Key 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). An account whose credit is exhausted answers 402 (see When the balance runs out).

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:

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:

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:

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). 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:

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.