Data guarantees

Last updated 2 November 2026

Rely on your Machine’s database: a commit is durable once synced(), the call that waits until two of the region’s three replicas hold it, resolves, whatever then happens to the Machine or its host.

• Answer a request after synced() resolves, and what you answered survives any sleep, crash or host loss.
• A crash loses at most the last 16 MiB of commits synced() has not confirmed, plus one commit, when your program opens the database as Keep data shows.
• A Machine’s database has the same size limit as every Tonbo database.
• Memory, and files outside the Machine’s Volume, are not durable (see Sleep guarantees).
• Not yet promised: that a database keeps its data across a minor release of Ursula, the service that stores it (see What survives).

How to write the program that does this is on Keep data in its database and Volume.

When a commit is durable

The database is a Tonbo database in the Machine’s region, not a file on its host, so it follows the rule every database does. Where a commit is at each moment:

  A CALLER: an agent, a browser, a webhook sender
     |  HTTPS, to the Machine's name
     v
  TONBO, at the edge of the Machine's region      wakes the Machine and holds
     |                                             the request up to 25 s
     v
  YOUR MACHINE, awake
  +------------------------------------------+
  |  your program --commit--> its database's |    t0  the commit returns: it is
  |                           local copy     |        on the Machine's disk
  |  memory, processes, files: gone at sleep |
  +--------------------+---------------------+
                       |  in the background
                       v
  TONBO, in the same region: three replicas, one per zone
                       |                          t1  two of three hold it:
                       |                              synced() resolves
                       v
  object storage, in the same region              t2  older commits move here
                       |
                       v
  THE NEXT WAKE: the Machine boots fresh, and your program opens the
  database and finds every synced commit

Word for word

• The exact meaning of synced(). synced() resolves once two of the database's three replicas, each in its own availability zone of the region, hold the commit in memory; it does not wait for a write to their disks. Tonbo keeps no backups of a Machine's database.

Where the database lives and how the Machine reaches it is on Database wiring.

What survives

A synced commit survives every sleep and wake, a lost host and Tonbo’s upgrades of its hosts and of Firecracker, the virtual machine software a Machine runs in. Keeping it across a minor release of Ursula is not promised until Tonbo serves two such releases side by side.

• A cell, below, is Tonbo’s hosts in one region.
• Suspend, resume and discard, below, would keep a Machine across a sleep; Tonbo does not suspend Machines, so every sleep stops one and every wake boots fresh.

Word for word

What	Promise
A SQLite-over-Ursula commit after synced() resolves	Durable: it survives sleep, wake, suspend, resume, discard, host loss, and Tonbo's upgrades of hosts and Firecracker. Once customers' databases are on a cell, Tonbo does not reset or wipe that cell's Ursula. A database keeps its data across an Ursula minor release only once D11's N/N−1 window exists.

If the Machine crashes

A crash loses only commits synced() has not confirmed: at most 16 MiB of them plus one commit when your program opens the database as Keep data shows, and more when it does not. Answer only after synced() and no caller ever sees one of them.

Word for word

• What a crash can lose. A crash of the Machine or the loss of its host can lose the commits of a database that synced() has not confirmed: at most what maxPendingBytes lets wait, counted in compressed bytes, plus the one commit that passes it. On a Machine one commit changes at most 16 MiB of pages, and TONBO_VFS_MAX_PENDING_BYTES holds 16 MiB for the program to pass to open() as maxPendingBytes; a program that passes none lets the database package's default of 64 MiB wait. An application that answers before synced() resolves can expose such a commit.

How much it holds

A Machine’s database holds as much as any Tonbo database.

Word for word

• Size. A Machine's database holds what fits a snapshot of 256 MiB compressed, as every Tonbo database does.

Its Volume

A write to a Machine’s Volume is durable once a flush issued after it returns: fsync, fdatasync or sync, a write opened with O_SYNC or O_DSYNC, or an unmount. A flush returns only after the region’s replicas hold what it covers, as synced() does for a commit. close on its own is not a flush. A write no returned flush covers can be lost when the Machine or its host fails; after such a failure the Volume shows its blocks as they stood at one instant, no earlier than the last returned flush.

There are no Volume snapshots, backups or resizing. A Volume is not a backup, and it does not protect against your own deletes. Volumes are not offered yet, so none of this is a promise until they are.