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, and it refuses to load into SQLite older than 3.50.4. Elsewhere, build it from source as the package README describes.

loadUrsulaVfs()

From @tonbo/sqlite-ursula.

function loadUrsulaVfs(path?: string): DatabaseSync

Loads the extension once per JavaScript thread and returns the thread’s control connection, an in-memory DatabaseSync with the functions below. The library is path, else 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, 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.
`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. 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 is db-uwal. The sqlite3 shell, node:sqlite 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).