Cold starts

Last updated 29 October 2026

Read this when your program starts on a new machine: when an open rebuilds the local copy from Tonbo, how long that takes, and how to avoid it.

A process rebuilds the database when it opens it on a new machine, or after its cache root, the directory that holds its local copy (the dir option of open()), was deleted: it downloads the latest snapshot and replays the commits since it. A process that restarts with the same cache root resumes from it instead, after a crash or a reboot too.

How long it takes

In a test cluster of the same shape in the same region, a client inside the cluster rebuilt a 100 MB database in 0.3 to 1.1 seconds. From your host, add the download: the latest snapshot, up to 256 MiB compressed, plus the log written since it. A database near the size limit can take tens of seconds to rebuild over a slow link.

Avoiding them

Keep the cache root on a disk that outlives the process, such as a volume of the same pod, so a restart resumes instead of rebuilding.

Short-lived processes

A database works in any Node.js process with a writable local directory for its cache, /tmp included, as long as only one process opens it at a time. A process that starts without the last one’s directory, such as a fresh sandbox, a new container or a serverless function, rebuilds the local copy from Tonbo when it opens the database, a cold start, and its open counts one write. Killed with its disk, a process can lose every commit since its last resolved synced(), so await synced() after each step that must survive, not only before it exits. Processes that open the same database at once, as concurrent invocations of a function do, take it over from each other, and the commits of all but the last are refused.

Such a process pays the rebuild above at every start, and one write for each open (see Pricing); before it exits, or is stopped, it has to have awaited synced() for everything it must keep (see close()).