Python SDK reference

Last updated 3 November 2026

Every export of sqlite-ursula 0.11.3.dev0, the Python package that opens a Tonbo database by its URL as a sqlite3 connection: each function’s parameters, defaults, return value and errors, page by page.

To get started, follow the Python quickstart and Connect from Python. Every declaration these pages show is read from the release’s wheel, so it is the release’s own.

Install

pip install sqlite-ursula==0.11.3.dev0

Or, in a uv project, uv add sqlite-ursula==0.11.3.dev0. Pin the exact release, as these commands do: a later release can change the cache format and the server releases it works with, and the exact pin is what lets pip and uv install a pre-release without a flag. For LangGraph, install the langgraph extra:

uv pip install 'sqlite-ursula[langgraph]==0.11.3.dev0'

Versions

This reference describes sqlite-ursula 0.11.3.dev0, built from tonbo-io/ursula 8423f6eb. Python uses the pre-release sqlite-ursula 0.11.3.dev0 until 0.11.3 is published to PyPI. It is of the same minor release line as the Node.js package, @tonbo/sqlite-ursula 0.11.4 (see the Node.js SDK reference), and runs the same SQLite extension inside your process. sqlite_ursula.__version__ is the release, as a string:

import sqlite_ursula

print(sqlite_ursula.__version__)  # "0.11.3.dev0"

Platforms

CPython 3.11 or later (Requires-Python: >=3.11), the free-threaded builds included, on one of the platforms the release builds a wheel for. On any other, such as an Intel Mac or Windows, pip installs it without the library that runs inside SQLite, and open() raises host_unsupported.

Pythons that run it

The package loads its extension into the SQLite of Python’s own sqlite3 module, so that module must load extensions and run a recent SQLite. On a laptop, a uv-managed CPython is the usual answer.

python -m sqlite_ursula checks the Python it runs in: it loads the extension as open() would, prints what it found, and exits 0 when this Python can run the package and 1 when it cannot, with the reason and a fix: line naming a Python that can. It needs no network and no credential.

python -m sqlite_ursula

sqlite-ursula 0.11.3.dev0
python: <version> (CPython) at <path to python>
sqlite: <version>
extension loading: yes
extension: <path to the library> (bundled)
result: ok: this Python can host sqlite-ursula

Credentials

The package takes a bearer token, a string, which every request of the process carries: a Tonbo API key that acts as you, sent as it is (see Sending the key directly), or an access token exchanged from a key, which an Agent’s key needs and which lasts 10 minutes (see The token exchange). Pass it as open(..., token=...), or replace it with set_token(). The process holds one token for every database it opens. This release takes no token provider and never exchanges a key itself.

The token reaches what its key reaches (see What a key can reach): a key narrowed to other databases is refused with forbidden, and a read-only key opens a database only with read_only=True.

Conventions

• Every error the package raises is an UrsulaError with a kind, what failed, and an action, what to do. Branch on action. Any other error, such as a constraint violation, is sqlite3’s, unchanged.
• Every timeout is in seconds, as a number. Waits that take None wait without a limit, and a value the package cannot take raises invalid_argument before any request.
• Statements are local. A commit returns once it is on this machine; call db.synced() before anything outside the process acts on it.
• Any thread may use a connection, and the a-prefixed calls wait on the asyncio event loop instead of blocking it.
• Open databases after a fork, never before: in a child forked after its parent opened one, the package raises forked.
• The package and its extension read a few environment variables, such as URSULA_VFS_TOKEN_FILE and SQLITE_URSULA_VFS; they are the Node.js package’s too (see The extension).

Exports

sqlite_ursula exports:

sqlite_ursula.langgraph, which the package never imports itself, exports: