open() and aopen()

Last updated 3 November 2026

open() opens a database by its URL and makes this process its writer; aopen() is the same call for asyncio. This page lists every parameter, what they return and what they raise.

A database’s URL comes from tonbo database show <name> --json, the console or the Management API. Connect from Python walks through a first open.

open()

def open(
    url: str,
    *,
    token: str | None = None,
    dir: str | os.PathLike[str] | None = None,
    read_only: bool = False,
    recreate: bool = False,
    max_pending_bytes: int | None = None,
    timeout: float = DEFAULT_OPEN_S,
    busy_timeout: float = DEFAULT_BUSY_S,
    **connect_kwargs: Any,
) -> UrsulaConnection: ...

import os

import sqlite_ursula

db = sqlite_ursula.open(
    os.environ["NOTES_URL"],
    token=os.environ["TONBO_API_KEY"],
    dir="./notes-cache",
    timeout=10,
)

The first open of a database in the process binds its local cache, catches it up from Tonbo and claims the database, so any earlier writer is fenced: from then on its statements raise fenced. Later opens of the database in the process return another connection on the same binding, with no network, and concurrent opens, from any thread, share one bind and its outcome. It blocks the calling thread for at most timeout.

Parameters

Read-only opens

In a process that owns the database, read_only=True returns a read-only connection on the owner’s binding: it sees the owner’s latest commits, and its synced() waits as the owner’s does. In any other process it builds or catches up a reader cache of its own to the database as of the open, claims nothing and does not follow later commits, and its synced() returns at once. Close every read-only connection of the process and open again to read newer commits.

Credentials

token is a key that acts as you, sent as it is (see Sending the key directly), or an access token exchanged from a key (see The token exchange). A key that acts as an Agent must be exchanged first: sent as it is, the open raises unauthorized once its timeout passes (see an Agent’s key). The key must reach the database, and a read-only key opens it only with read_only=True, since claiming the database writes to it.

Returns

An UrsulaConnection, a sqlite3.Connection subclass, or the factory class given. Its status()["state"] is live, or provisional when Tonbo was unreachable and a trusted cache that claimed the database before served the open: reads come from the cache, commits wait, and the state turns live once Tonbo answers (see state).

Errors

• UrsulaSetupError when the open cannot succeed as asked, such as invalid_argument, invalid_url, not_found, bound_elsewhere, host_unsupported or forked. Its action is fix, or retry for in_use and claim_races. A database you have not created is on Troubleshooting.
• UrsulaUnavailableError when timeout passed first: the last condition the open met, such as unreachable or unauthorized, or cancelled when it met none (see Troubleshooting).
• KeyboardInterrupt on Ctrl-C, once the open cancelled its request. A Ctrl-C in the open’s first instant can miss the cancel, and that request then runs on in the background.

Retries

An open is safe to call again: it never creates a database (unless recreate recreates a missing one), and each call either binds, joins a bind under way or returns a connection on the binding there is. Call it again after an error whose action is retry, with a backoff. Never call it in a loop after fenced: each open takes the database back from the other writer.

import time

import sqlite_ursula

for attempt in range(5):
    try:
        db = sqlite_ursula.open(url, token=key)
        break
    except sqlite_ursula.UrsulaError as error:
        if error.action != "retry":
            raise  # fix, reopen or stop: retrying the same call cannot help
        time.sleep(2**attempt)

aopen()

async def aopen(
    url: str,
    *,
    token: str | None = None,
    dir: str | os.PathLike[str] | None = None,
    read_only: bool = False,
    recreate: bool = False,
    max_pending_bytes: int | None = None,
    timeout: float = DEFAULT_OPEN_S,
    busy_timeout: float = DEFAULT_BUSY_S,
    **connect_kwargs: Any,
) -> UrsulaConnection: ...

import asyncio
import os

import sqlite_ursula


async def main() -> None:
    async with asyncio.timeout(10):  # cancels the open, too
        db = await sqlite_ursula.aopen(
            os.environ["NOTES_URL"], token=os.environ["TONBO_API_KEY"]
        )
    db.execute("INSERT INTO notes(body) VALUES (?)", ("hello",))
    db.commit()
    await db.asynced()

open() for asyncio: the same parameters, the same connection and the same errors, and it waits for the bind on the event loop instead of blocking it. Cancelling it, as asyncio.timeout around it does, cancels the bind and raises CancelledError, so no bind goes on to claim the database after the caller gave up. Statements on the connection it returns still run on the calling thread, as they do with sqlite3; wait for Tonbo with asynced() or agate().