Database wiring

Last updated 2 November 2026

Read this when you need to know how a Machine reaches its database and what the platform sets for it.

Where it lives

A Machine’s database is the stream m.<id> among your account’s databases in the Machine’s region, with two more of the Machine’s streams beside it, which no page here asks you to use. Tonbo creates it with the Machine, and deletes it after the Machine’s last stop once you delete the Machine. It is served by Ursula in Tonbo, like every database.

Its token

The Machine has its own identity, which owns m.<id>. For each wake the controller mints a token for it, the host writes it to /run/tonbo/token, in memory, and replaces it before it expires; URSULA_VFS_TOKEN_FILE points the package at it, so a program passes no key. Members of the account can read the database too.

The platform’s settings

• URSULA_VFS_MAX_COMMIT_BYTES, 16 MiB of pages per transaction, which the package reads itself.
• TONBO_VFS_MAX_PENDING_BYTES, 16 MiB of compressed commits, which a program passes as maxPendingBytes. The package admits a transaction while what waits is at most that and counts the commit once it is logged, so what waits is at most 16 MiB plus the one commit that passes it, which a drain can send.
• The Machine’s quota toward Tonbo: 40 requests and 4 MiB a second, and 4 live reads (open tails of a stream, which the package does not use), with a burst of 1 s, for all of the Machine’s streams together; a request past them is refused until the allowance refills.
• The rest of the names the platform sets, among them TONBO_TOKEN_FILE, TONBO_LOGS_URL, TONBO_ACTIVATION_FILE and TONBO_SECRETS_DIR, are reserved: no program reads them, and a Machine whose environment variables set any of them fails to wake.

The drain

The host records each cache directory the program opens. After a planned stop, it sends what those directories still had to send, within 60 s (see Stops and the drain). A crash or the loss of the host skips it, which is why a program answers only after synced().

How the database works

The rest is the same for every database: The SQLite extension, Replication and synced(), Ownership and fencing and Snapshots and S3, which link down to Ursula’s and SQLite’s documentation.