> Fetch the index of every Tonbo docs page as Markdown at https://tonbo.dev/llms.txt

# 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](https://tonbo.dev/docs/databases/connect.md) opens it.

### Create a database before you open it

Opening never creates a database (see [States](https://tonbo.dev/docs/databases/manage.md#states)). Create it in the console, with the CLI or through the API, and open it once it is active.

**Do**

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

**Don’t**

```shell
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](https://tonbo.dev/docs/platform/api-keys.md#key-scope)).

**Do**

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

**Don’t**

```shell
# 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](https://tonbo.dev/docs/databases/manage.md#regions)).

### 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](https://tonbo.dev/docs/databases/backups.md)).

**Do**

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

**Don’t**

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