Rules: setup

Last updated 29 October 2026

Check these rules when you create databases and keys for a program: each keeps it working, its key narrow and its data yours to take.

The examples use the connection open() returns, a node:sqlite DatabaseSync, as Connect opens it.

Create a database before you open it

Opening never creates a database (see States). Create it in the console, with the CLI or through the API, and open it once it is active.

tonbo database create notes
node app.mjs # open("notes") finds it

node app.mjs # open("notes-2") rejects with TonboError, kind database_not_found

Give each program its own narrowed key

A key that acts as you and is not narrowed reaches every database and stream of every account you belong to, and a process carries one token for all its databases (see What a key can reach).

tonbo api-key create notes-app --database notes

# Your own key, unnarrowed, deployed with the application:
TONBO_API_KEY=tbo_... node app.mjs

Create a database where its program runs

Every synced() waits for a round trip to the database’s region, which is fixed when the database is created. Pick the region nearest the program (see Regions and URLs).

Export a plain SQLite copy, never the cache directory

An export opens in any SQLite tool, so it is how a database leaves Tonbo and how you go back after a mistake of your own, while the cache directory’s files open only through the package (see Backups).

db.prepare("VACUUM INTO ?").run(`/backups/notes-${day}.db`); // a plain SQLite file

// Copying the cache directory: its files are not plain SQLite files.
cpSync("notes-cache", "/backups/notes-cache", { recursive: true });