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

# SQL functions

Last updated 29 October 2026

The extension’s SQL functions, for hosts other than Node.js; the Node.js package calls them for you.

The extension is a SQLite loadable library, prebuilt for the platforms on [Requirements](https://tonbo.dev/docs/databases/connect.md#requirements), and it refuses to load into SQLite older than 3.50.4. Elsewhere, build it from source as the [package README](https://www.npmjs.com/package/@tonbo/sqlite-ursula) describes.

## loadUrsulaVfs()

From `@tonbo/sqlite-ursula`.

```text
function loadUrsulaVfs(path?: string): DatabaseSync
```

Loads the extension once per JavaScript thread and returns the thread’s control connection, an in-memory [DatabaseSync](https://nodejs.org/docs/latest-v22.x/api/sqlite.html#class-databasesync) with the functions below. The library is `path`, else [SQLITE_URSULA_VFS](https://tonbo.dev/docs/reference/nodejs/environment.md#sqlite-ursula-vfs), else the prebuilt `@tonbo/sqlite-ursula-<platform>`, an optional dependency. To load another library, call it with a path before any other call of the package; later calls return the connection already loaded. A library older than the package, one without `ursula_classify`, fails here with `UrsulaSetupError` `local_setup` (since 0.11.2).

## Functions

Each returns JSON text. An error is `SQLITE_ERROR` with the message `<function>: <kind>: <message>`, whose kind is one of [the package’s kinds](https://tonbo.dev/docs/reference/nodejs/errors.md), or `forked` (below); `ursula_classify` names its action and class.

| Function | What it does |
| --- | --- |
| `ursula_open(url, dir, options_json, timeout_ms)` | Binds and claims the stream under the cache root `dir` (NULL or empty for the default). It returns `{done, path, name, state}`, or `{done: false, request}` while the open goes on; a `timeout_ms` of 0 returns at once. Open `path` with the host’s SQLite afterwards. |
| `ursula_synced(path, timeout_ms)` | `{synced, ticket, target, acknowledged}`. With `synced` false, the ticket resolves when a `synced` event of the path reaches it. A reset fails it. |
| `ursula_events(cursor, timeout_ms)` | `{cursor, events}`: the events from `cursor` on, such as `synced`, `condition`, `reset` and, for a `tonbo_resolve`, `resolved` (since 0.11.2), waiting at most `timeout_ms` for one. |
| `ursula_cancel(request)` | Gives up an open in progress, or a resolve (since 0.11.2), and returns what it ended with, `{kind, action, class, message}`, or `null` when it had bound. Its `class` is there since 0.11.2. |
| `ursula_status(path)` | The database’s status, the object on [Status](https://tonbo.dev/docs/reference/nodejs/status.md). |
| `ursula_stats(path)` | Drains the database's measurements of each commit and checkpoint since the last call. |
| `ursula_set_token(path, token)` | The bearer token requests carry from now on, for the whole process. NULL or empty goes back to `URSULA_VFS_TOKEN_FILE`. |
| `ursula_import(url, file, options_json, timeout_ms)` | Imports a plain SQLite file as a new stream’s first snapshot, blocking; its `timeout_ms` must be positive. |
| `ursula_classify(message, errcode, path)` | What a failure is, from SQLite’s message and result code, since 0.11.2: `{kind, action, class, message, fix, request_id}`, where `class` is the error to throw (`write_refused`, `reset`, `unavailable` or `setup`), or `null` for SQLite’s own errors. `path` is the database a statement ran on, whose state names the statement’s I/O error; pass NULL for a SQL function’s error. `fix` and `request_id` are `null` for every failure of the extension. |
| `tonbo_resolve(name_or_url, options_json, timeout_ms)` | Resolves a Tonbo database by name as the `/tonbo` entry does, since 0.11.2: the key is `api_key` in `options_json`, else `TONBO_API_KEY`, else the login file, and the origins are `api_origin` and `auth_origin`, else [their variables](https://tonbo.dev/docs/reference/nodejs/environment.md#by-name). Unless `own_token` is set or `URSULA_VFS_TOKEN_FILE` is in use, the key becomes the process’s source of Streams tokens, and the first one is held before it answers `{done, url, name, key_tokens}`. A failure is `{done: true, error}`; a `timeout_ms` of 0 returns `{done: false, request}` at once and a `resolved` event later. |

A host reopens a database that retired through `ursula_open`: until then, a plain open of its path is refused.

In a child process forked after the extension started, with its first `ursula_open`, `ursula_events`, `ursula_import` or `tonbo_resolve`, every function fails with the kind `forked`, action `fix`, and every file method of a bound database fails without running, so the child cannot stall on `synced()` or write the parent’s databases (since 0.11.2). Open the databases after the fork; a child forked before the start opens them as any process does.

## Cache files

A cache’s files are not SQLite files outside the extension: the db file holds a marker in place of SQLite’s header magic, and its [WAL](https://sqlite.org/wal.html) is `db-uwal`. The `sqlite3` shell, [node:sqlite](https://nodejs.org/docs/latest-v22.x/api/sqlite.html) without the extension and a connection opened before the extension loaded fail with `SQLITE_NOTADB` and change nothing. To read a database with plain SQLite, export it (see [Export a copy](https://tonbo.dev/docs/databases/backups.md#export)).