The account's databases, each one stream at its url; Control creates and deletes them. The overview covers what every operation shares: authentication, roles, errors, pagination, idempotency and If-Match.
Needs account.read, which owner, admin and member hold. A narrowed key may call it.
Live rows of the listed kinds (contracts/streams-databases/v1.json kinds whose api is databases: a member's databases and each Machine's database, with kind and the owning Machine as owner_id), creating, active or deleting, in every region, by name. A key narrowed to databases sees only the databases it reaches, and a key narrowed to buckets, or by name to streams alone, sees none. last_write_at and stored_bytes come from each region's meter; unavailable_regions names the regions whose sizes could not be read, whose databases then show null sizes (and, with include=daily_writes, those whose daily writes could not be read).
Parameters
Name
In
Type
Required
Description
prefix
query
string
no
Only databases whose name starts with this prefix. 1 to 85 characters. Matches ^(?!m\.)(?!vol\.)(?!s\.)(?!session\.)(?!proc\.)[a-z0-9][a-z0-9._-]{0,84}$.
include
query
one of "daily_writes"
no
daily_writes adds each database's daily_write_units, its write units of the last 7 UTC days, from one more read of each region's meter.
cursor
query
string
no
Opaque cursor tied to the original query shape. At least 1 characters.
limit
query
integer
no
The most items one page holds, 1 to 200; 50 when omitted. A page may hold fewer; read on with next_cursor until it is null. Default 50. 1 to 200.
The key’s role does not hold the capability the operation needs, the key is narrowed away from the resource, or the account already holds as many of the resource as it may.
No
Use a key whose role holds the capability, or one that is not narrowed; delete what you no longer need, or ask for a higher limit. (more)
Needs databases.write, which owner, admin and member hold. A narrowed key may not.
Any member creates databases; a narrowed key never does. A name is unique within the account across every region while a database holds it, and is free again once that database is deleted. The region is fixed at creation; without one, the database goes to the region whose default is true. An optional expires_at, at least 60 seconds after the creation and fixed for the database's life, has Tonbo delete the database within a minute after it passes, as a deletion would; a replay is not held to the 60 seconds. Databases and streams expire by the same rule; a Machine's database never expires. The answer is 201 once the database is active and 202 while it is still being created; read it again until it is active. A replay with the same Idempotency-Key answers the same database; the key reused for another name, region or expiry answers 409. An account holds at most limits.databases_per_account live databases (contracts/streams-databases/v1.json); past that the answer is 403 and names whom to contact. An account whose credit is exhausted answers 402.
Parameters
Name
In
Type
Required
Description
Idempotency-Key
header
string
yes
A value you choose for this one creation, 1 to 255 characters, such as a new UUID. Send a new one for each resource you create, and the same one only to retry that request after a timeout or a lost answer: the retry answers what the first request created, in its current state, and never creates a second. A key reused for a different database, stream or Machine answers 409. 1 to 255 characters.
Request body
application/json, required. Unknown fields are refused.
Field
Type
Required
Description
name
string
yes
The new database's name. 409 when a live database of the account in any region has it; a deleted database's name is free again. 1 to 85 characters. Matches ^(?!m\.)(?!vol\.)(?!s\.)(?!session\.)(?!proc\.)(?!(?:streams|new)$)(?!.*\.\.)[a-z0-9](?:[a-z0-9._-]{0,83}[a-z0-9])?$.
region
string
no
The database's region, fixed for its life; the region whose default is true when omitted. A region closed to databases answers 503. Matches ^[a-z]{2}-[a-z]+-[0-9]$.
expires_at
string (date-time)
no
When the database expires, an RFC 3339 time, fixed for its life; it never expires when omitted. A new database's expiry must be at least 60 seconds after its creation by the registry's clock (422 on expires_at otherwise); a replay of the Idempotency-Key must name the same time and is answered however near or past that time is. Once it has passed, Tonbo deletes the database within a minute, as a deletion would.
The key’s role does not hold the capability the operation needs, the key is narrowed away from the resource, or the account already holds as many of the resource as it may.
No
Use a key whose role holds the capability, or one that is not narrowed; delete what you no longer need, or ask for a higher limit. (more)
The name is held by another live resource of the account, the Idempotency-Key already created another resource or one since deleted, or the resource’s current state does not allow the change. detail says which, and errors names the field.
No
Pick another name or a new Idempotency-Key, or read the resource again and act on its current state. (more)
The region could not be reached or read, or it takes no new resource of this kind. Every answer carries Retry-After.
After Retry-After
Send the request again after Retry-After; if detail says the region takes no new resource of this kind, name another region. (more)
Retries
Send a new Idempotency-Key with each request and the same one when you send it again: a repeat answers what the first request did, and the key reused for a different request answers 409 (see Idempotency).
429 and 503 carry Retry-After: wait that many seconds, then send the same request again.
GET /v1/databases/{name} · CLI: tonbo database show
Needs account.read, which owner, admin and member hold. A narrowed key may call it.
A live database of the account, with its url, expires_at and state; clients that open a database by name, such as @tonbo/sqlite-ursula/tonbo, resolve it here. A key narrowed to databases reads the databases it names and those under its prefixes, and any other name answers 404 with the same status and body as a database that does not exist, so the narrowing does not disclose whether the account's other databases exist. A key narrowed to buckets, or by name to streams alone, reads none.
Parameters
Name
In
Type
Required
Description
name
path
string or string
yes
The database's name, or a Machine's database as m.<machine id>.
The key’s role does not hold the capability the operation needs, the key is narrowed away from the resource, or the account already holds as many of the resource as it may.
No
Use a key whose role holds the capability, or one that is not narrowed; delete what you no longer need, or ask for a higher limit. (more)
Needs databases.publish, which owner and admin hold. A narrowed key may not.
Owners and admins, on an active database. Anonymous readers reach only the database's current incarnation. A Machine's database answers 409 managed_by_machine (contracts/streams-databases/v1.json kinds.managed_refusal).
Parameters
Name
In
Type
Required
Description
name
path
string or string
yes
The database's name, or a Machine's database as m.<machine id>.
If-Match
header
string
no
Optional conditional update; omitted requests use last-write-wins. At most 500 characters.
Request body
application/json, required. Unknown fields are refused.
Field
Type
Required
Description
public_read
boolean
yes
true publishes the database: anyone with its URL reads it without a key, and writes still need one. false makes it private again.
The key’s role does not hold the capability the operation needs, the key is narrowed away from the resource, or the account already holds as many of the resource as it may.
No
Use a key whose role holds the capability, or one that is not narrowed; delete what you no longer need, or ask for a higher limit. (more)
The name is held by another live resource of the account, the Idempotency-Key already created another resource or one since deleted, or the resource’s current state does not allow the change. detail says which, and errors names the field.
No
Pick another name or a new Idempotency-Key, or read the resource again and act on its current state. (more)
Needs databases.write, which owner, admin and member hold. A narrowed key may not.
Any member deletes databases; a narrowed key never does. The answer is 200 once the database is deleted (state is deleted) and 202 while it is still being deleted. Its name is free again once it is deleted; its usage this month stays in /usage/databases. Repeating the request answers the database being deleted. A Machine's database is deleted with its Machine and answers 409 managed_by_machine (contracts/streams-databases/v1.json kinds.managed_refusal).
Parameters
Name
In
Type
Required
Description
name
path
string or string
yes
The database's name, or a Machine's database as m.<machine id>.
The key’s role does not hold the capability the operation needs, the key is narrowed away from the resource, or the account already holds as many of the resource as it may.
No
Use a key whose role holds the capability, or one that is not narrowed; delete what you no longer need, or ask for a higher limit. (more)
GET /v1/databases/{name}/usage · CLI: tonbo database activity
Needs account.read, which owner, admin and member hold. A narrowed key may call it.
A live database's writes per hour or day (UTC) over a window of at most 31 days, by default the last 24 hours hourly or the last 30 days daily, through the current step, and its size at the end of each step (now, for the current one), from its region's meter, with the meter's checkpoint as as_of and the database's last write. A Machine's database counts its Machine's logs and inbox streams in its writes, as its usage does; its size is the database's own. Only the database as it is now counts, not an earlier database of the same name. A write counts in the step that holds its settlement hour, so the current step grows until it ends; a step that starts after now answers null. A key narrowed to databases reads the databases it reaches, and any other name answers 404 with the same status and body as a database that does not exist. 503 when the database's region cannot be read.
Parameters
Name
In
Type
Required
Description
name
path
string or string
yes
The database's name, or a Machine's database as m.<machine id>.
granularity
query
one of "hour" or "day"
no
One point per UTC hour (the default) or per UTC day. Default "hour".
from
query
string (date-time)
no
The window's start, on a UTC hour (or day, for daily points); by default 24 hours (or 30 days) before to.
to
query
string (date-time)
no
The window's end, exclusive, on a UTC hour (or day), at most 31 days after from; by default the end of the current hour (or day).
The key’s role does not hold the capability the operation needs, the key is narrowed away from the resource, or the account already holds as many of the resource as it may.
No
Use a key whose role holds the capability, or one that is not narrowed; delete what you no longer need, or ask for a higher limit. (more)
Write units committed in the step (contracts/billing/streams-prices-v1.json write_unit_bytes each); null for a step that starts after now. At least 0.
append_bytes
integer or null
yes
Bytes appended in the step; null for a step that starts after now. At least 0.
records
integer or null
yes
Records appended in the step; null for a step that starts after now. At least 0.
log_bytes
integer or null
yes
The retained log at the step's end (now, for the current step), as stored_bytes.log counts it; null before the meter's first sample and for a step that starts after now. At least 0.
snapshot_bytes
integer or null
yes
The snapshots at the step's end, as stored_bytes.snapshot counts them; null before the meter's first sample and for a step that starts after now. At least 0.
The database's name; a Machine's database is m.<machine id>.
kind
one of "database" or "machine"
yes
database for one a member created, machine for a Machine's own, which its Machine creates and deletes.
owner_id
string (uuid) or null
yes
The Machine that owns a machine row; null for a member's database.
region
string
yes
The region the database lives in, fixed for its life. Matches ^[a-z]{2}-[a-z]+-[0-9]$.
url
string (uri)
yes
The database's data-plane address, {region's database origin}/{account id}/{name}; open it with the SQLite on Ursula client.
expires_at
string (date-time) or null
yes
When the database expires, fixed at creation; null when it never expires, and always for a Machine's database. Once it has passed, Tonbo deletes the database within a minute, as a deletion would, and its name is free again.
incarnation
string or null
yes
Ursula's Stream-Incarnation as a decimal; null while creating. A client that cached the URL resolves the database again when it changes. Matches ^(0|[1-9][0-9]{0,19})$.
state
one of "creating", "active", "deleting" or "deleted"
yes
deleted appears only in the answer to the deletion that completed it.
public_read
boolean
yes
Whether anonymous reads are served.
created_at
string (date-time)
yes
When the database was created.
created_by
string
yes
The member who created it, or for a Machine's database the member who created the Machine. Matches ^[a-z0-9._-]{1,64}$.
last_write_at
string (date-time) or null
yes
The last write the region's meter saw, up to a minute behind; null until a host first opens it (an open writes; the create does not), and when its region is unavailable.
stored_bytes
object
yes
What the region's meter last saw stored; null when not yet reported or unavailable.
stored_bytes.log
integer or null
yes
Bytes of the database's retained log, as Tonbo stores it; null when not reported. At least 0.
stored_bytes.snapshot
integer or null
yes
Bytes of its snapshots; null when not reported. At least 0.
measured_at
string (date-time) or null
no
When the region's meter last read last_write_at and stored_bytes (every minute while it is healthy); null when the database is not yet metered or its region is unavailable. Optional; absent from older answers.
writes
one of "accepting", "suspended" or null
no
Whether Tonbo accepts writes to the database now. suspended while the account has no credit left, when writes answer 402 PAYMENT_REQUIRED and reads continue; writes resume shortly after a top-up. It is the account's state, the same for each of its databases and streams. Only in the answer for one database (show and update), never in a list; null when it could not be read.
daily_write_units
array of integer or null
no
The database's write units on each of the last 7 UTC days, oldest first, the last being today so far, for a sparkline: only in a list asked for it with include=daily_writes, never in a show; null when its region could not be read. Only the database as it is now counts, not an earlier database of the same name. 7 to 7 items.
A database's or stream's writes and size over a window, from its region's meter.
Field
Type
Required
Description
name
string
yes
The database's or stream's name.
region
string
yes
Its region, whose meter answered. Matches ^[a-z]{2}-[a-z]+-[0-9]$.
granularity
one of "hour" or "day"
yes
One point per UTC hour or per UTC day.
from
string (date-time)
yes
The window's start.
to
string (date-time)
yes
The window's end, exclusive.
as_of
string (date-time) or null
yes
When the region's meter last completed a poll, about once a minute while it is healthy; writes and sizes after it are not counted yet. Null when it has never completed one.
last_write_at
string (date-time) or null
yes
The last write the region's meter saw, as the show answers it; null before the first write.