Docs
PricingConsole

Quickstart: SQLite

Last updated 29 October 2026

View .md

From sign-in to a first replicated commit with node:sqlite, from your laptop or any machine with Node.js 22.19 or later and internet access, with nothing to allowlist, on Linux (x64 or arm64) or macOS on Apple silicon; on any other platform, such as an Intel Mac, build the package’s SQLite extension from source first (see Requirements).

Sign in

Sign in at tonbo.dev with GitHub or Google. A new account asks you to choose a username: it names your personal account, which holds your databases, streams and keys, and appears in the console’s addresses. You can change it once every 90 days.

Create a database

Create a database named notes. It goes to the default region, us-east-1, unless you choose another (see Regions and URLs): pick the one nearest where your program runs. With the CLI, name it with --region, as in tonbo database create notes --region ap-southeast-1.

  1. Open Databases in the console.
  2. Choose Create database and name it notes.

The database is creating for a moment, then active. Node.js code opens it by name, and Python code by its URL, which tonbo database show notes and the console show (see Regions and URLs).

Create an API key

Give the program its own key, narrowed to notes: it reads and writes only that database, and may name one that does not exist yet. A key that acts as you and is not narrowed reaches every database and stream you can in its account (see What a key can reach).

  1. In the console, choose API keys in the sidebar.
  2. Choose New API key and narrow it to the database notes.
  3. Copy the key. It starts with tbo_ and is shown once.

On this machine, after tonbo login, a Node.js program can also open its databases with no key at all: open() falls back to your login (see Connect). Python does not, and the narrowed key is what any program uses anywhere else.

Install the package

npm install --save-exact @tonbo/sqlite-ursula@0.11.2

Keep this exact version (--save-exact records it without a range, since a later release can change what this page uses), and do not install with --omit=optional: the prebuilt extension for your platform is an optional dependency.

Check that npm added the prebuilt extension for your platform:

npm ls --all | grep @tonbo/sqlite-ursula-

It prints the extension’s package, such as @tonbo/sqlite-ursula-darwin-arm64 on a Mac with Apple silicon. If it prints nothing, npm skipped that optional package: install again without --omit=optional, or, on a platform with no prebuilt extension, build it from source (see Requirements).

Open and commit

Save this as app.mjs:

app.mjs
import { open } from "@tonbo/sqlite-ursula/tonbo";

// Opens notes by name with your API key; db is a node:sqlite DatabaseSync.
const db = await open("notes", { dir: "./notes-cache" });
db.exec("CREATE TABLE IF NOT EXISTS notes(id INTEGER PRIMARY KEY, body TEXT)");
db.prepare("INSERT INTO notes(body) VALUES (?)").run("hello"); // committed on this host
await db.synced(); // Tonbo now holds every commit made so far
console.log(db.prepare("SELECT count(*) AS notes FROM notes").get(), db.status().commits);
db.close();

Run it with the key from the API key step:

TONBO_API_KEY=tbo_... node app.mjs

It prints the count, then the commit counters with nothing pending: logged, confirmed and acknowledged are one number, the position of the last commit, and Node may set the counters over several lines:

[Object: null prototype] { notes: 1 } { logged: <n>, confirmed: <n>, acknowledged: <n>, pending: 0, pending_bytes: 0 }

Await synced() before anything outside the process acts on a commit, such as a response: until then the commit is only on this machine.

Rebuild it from Tonbo

Delete the local copy and run the program again. The open rebuilds the database from the copy Tonbo keeps, so the first row is still there and the count becomes 2:

rm -r notes-cache
TONBO_API_KEY=tbo_... node app.mjs

Then copy app.mjs to another machine, install the package and run it with the same key. It opens the same database, and the count becomes 3.

Add it to a project

In a project of your own, with the program’s API key in TONBO_API_KEY where the project keeps its secrets, never in its code:

  1. Create the database with tonbo database create notes, signed in with tonbo login, or in the console. tonbo database show notes prints State: active once it is ready.
  2. Install, keeping the exact versions:
    npm install --save-exact @tonbo/sqlite-ursula@0.11.2
    npm ls --all | grep @tonbo/sqlite-ursula- then prints the prebuilt extension for your platform.
  3. Where the program opens SQLite, open the database by name instead, with open from @tonbo/sqlite-ursula/tonbo: const db = await open("notes", { dir: "./notes-cache" }); It is a node:sqlite DatabaseSync, so the SQL stays as it is.
  4. Await db.synced() before anything outside the process acts on a commit: until then the commit is only on this machine (see synced()).

One process writes a database at a time: the last one to open it (see When two instances run).

Next steps