pi-durable-python 1.3.0__py3-none-any.whl

pi_durable/storage/scan.py

@@ -0,0 +1,57 @@
+"""Cursor and order helpers shared by storage backends."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, TypeGuard
+
+from ..errors import StorageRequestError
+from ..types import Cursor, ScanOrder
+
+
+@dataclass(frozen=True, slots=True)
+class ScanStart:
+    """Where a built-in storage scan starts: its order and the last ID a previous page returned."""
+
+    order: ScanOrder
+    after: int | None
+
+
+def _is_safe_int(value: object) -> TypeGuard[int]:
+    return isinstance(value, int) and not isinstance(value, bool) and abs(value) <= 9_007_199_254_740_991
+
+
+def scan_start(
+    requested: ScanOrder | None,
+    cursor: Cursor | None,
+    fallback: ScanOrder,
+) -> ScanStart:
+    """Resolve a scan's order and position, rejecting malformed and conflicting cursors."""
+
+    if requested is not None and requested not in ("ascending", "descending"):
+        raise StorageRequestError(f"Invalid scan order: {requested}")
+    if cursor is None:
+        return ScanStart(order=requested or fallback, after=None)
+    after = cursor.get("after")
+    if not _is_safe_int(after):
+        raise StorageRequestError("Invalid storage cursor")
+    stored = cursor.get("order")
+    if stored is not None and stored not in ("ascending", "descending"):
+        raise StorageRequestError("Invalid storage cursor")
+    order = valid_order(stored) or fallback
+    if requested is not None and requested != order:
+        raise StorageRequestError(f"The cursor continues a {order} scan; the query asks for {requested}")
+    return ScanStart(order=order, after=after)
+
+
+def valid_order(value: Any) -> ScanOrder | None:
+    return value if value in ("ascending", "descending") else None
+
+
+def next_cursor(id: int, order: ScanOrder) -> dict[str, Any]:
+    """Return the continuation of a scan whose last returned item has ``id``."""
+
+    return {"after": id, "order": order}
+
+
+__all__ = ["ScanStart", "next_cursor", "scan_start"]

pi_durable/storage/sqlite/__init__.py

@@ -0,0 +1,26 @@
+"""Portable SQLite storage backend and migrations.
+
+The host adapter lives in :mod:`pi_durable.storage.sqlite.posix`; this subpath stays free of it,
+so importing the portable backend never selects a driver.
+"""
+
+from .database import SqliteDatabase, SqliteExecutor, SqliteValue
+from .migrations import (
+    CURRENT_SQLITE_SCHEMA_VERSION,
+    SQLITE_MIGRATIONS,
+    SqliteMigration,
+    apply_sqlite_migrations,
+)
+from .storage import SqliteStorage, SqliteStorageOptions
+
+__all__ = [
+    "CURRENT_SQLITE_SCHEMA_VERSION",
+    "SQLITE_MIGRATIONS",
+    "SqliteDatabase",
+    "SqliteExecutor",
+    "SqliteMigration",
+    "SqliteStorage",
+    "SqliteStorageOptions",
+    "SqliteValue",
+    "apply_sqlite_migrations",
+]

pi_durable/storage/sqlite/database.py

@@ -0,0 +1,62 @@
+"""Portable SQLite facade contracts, translated from v1.3.0 ``sqlite/database.ts``.
+
+The core never imports a driver: it accepts any :class:`SqliteDatabase`, and the stdlib adapter in
+:mod:`pi_durable.storage.sqlite.posix` supplies one. Operations return awaitables rather than being
+``async`` functions so a caller's call order is the order the adapter observes, matching the
+promise-returning upstream facade.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from typing import Any, Protocol, TypeAlias, TypeVar
+
+SqliteValue: TypeAlias = None | int | float | str | bytes
+"""One positional binding accepted by the portable SQLite storage core."""
+
+T = TypeVar("T")
+
+
+class SqliteExecutor(Protocol):
+    """Asynchronous SQL operations shared by a database and its transaction handles.
+
+    ``exec`` runs SQL text without bindings and may contain several statements. ``run``, ``get``,
+    and ``all`` execute one statement with positional bindings. Adapters may cache prepared
+    statements by SQL text, so callers pass values as bindings instead of interpolating them.
+    """
+
+    def exec(self, sql: str) -> Awaitable[None]:
+        """Run one or more statements without bindings."""
+
+    def run(self, sql: str, *params: SqliteValue) -> Awaitable[None]:
+        """Run one statement with positional bindings."""
+
+    def get(self, sql: str, *params: SqliteValue) -> Awaitable[dict[str, Any] | None]:
+        """Return the first row of one statement, or ``None``."""
+
+    def all(self, sql: str, *params: SqliteValue) -> Awaitable[list[dict[str, Any]]]:
+        """Return every row of one statement."""
+
+
+class SqliteDatabase(SqliteExecutor, Protocol):
+    """Minimal database facade required by :class:`~pi_durable.storage.sqlite.SqliteStorage`.
+
+    ``transaction`` passes the callback a transaction handle. All work in the transaction must use
+    that handle; the handle is invalid after the callback settles. Adapters must queue unrelated
+    operations and other transactions until the transaction finishes. The returned awaitable
+    settles after commit or rollback. Calling the database itself (including ``transaction`` or
+    ``close``) from inside a callback therefore waits for that transaction and never settles.
+
+    When the callback raises, the adapter must roll the transaction back before re-raising that
+    same error. If rollback fails, it must raise a different error (here an ``ExceptionGroup``) so
+    callers cannot mistake the callback error for a guaranteed rollback.
+    """
+
+    def transaction(self, callback: Callable[[SqliteExecutor], Awaitable[T]]) -> Awaitable[T]:
+        """Run one callback as one SQL transaction."""
+
+    def close(self) -> Awaitable[None]:
+        """Release the connection; later operations reject or fail at the driver."""
+
+
+__all__ = ["SqliteDatabase", "SqliteExecutor", "SqliteValue"]

pi_durable/storage/sqlite/migrations.py

@@ -0,0 +1,191 @@
+"""Ordered SQLite schema history and atomic application, translated from v1.3.0 ``sqlite/migrations.ts``."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from .database import SqliteDatabase, SqliteExecutor
+from .schema import DEFAULT_SQLITE_SCHEMA, SqliteSchema
+
+
+@dataclass(frozen=True, slots=True)
+class SqliteMigration:
+    """One versioned, order-sensitive group of schema statements."""
+
+    version: int
+    statements: Sequence[str]
+
+
+def create_sqlite_migrations(schema: SqliteSchema) -> tuple[SqliteMigration, ...]:
+    """Build immutable, ordered schema history for a set of SQLite identifiers."""
+
+    tables = schema.tables
+    indexes = schema.indexes
+    # next_id is TEXT because JavaScript's SQLite driver rejects INTEGER results outside its safe
+    # integer range. The Python port keeps the column shape for persisted-record parity.
+    initial_schema = (
+        f"""CREATE TABLE {tables['durableMetadata']} (
+            singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
+            next_id TEXT NOT NULL,
+            next_seq INTEGER NOT NULL
+        ) STRICT""",
+        f"INSERT INTO {tables['durableMetadata']} (singleton, next_id, next_seq) VALUES (1, '2', 1)",
+        f"""CREATE TABLE {tables['recordIds']} (
+            id INTEGER PRIMARY KEY,
+            record_type TEXT NOT NULL
+                CHECK (record_type IN ('conversation', 'entry', 'task', 'submission', 'document'))
+        ) STRICT""",
+        f"""CREATE TABLE {tables['conversations']} (
+            id INTEGER PRIMARY KEY,
+            owner_conversation_id INTEGER,
+            owner_task_id INTEGER,
+            record TEXT NOT NULL CHECK (json_valid(record))
+        ) STRICT""",
+        f"CREATE INDEX {indexes['conversationsByOwnerConversation']} "
+        f"ON {tables['conversations']} (owner_conversation_id, id)",
+        f"CREATE INDEX {indexes['conversationsByOwnerTask']} "
+        f"ON {tables['conversations']} (owner_task_id, id)",
+        f"""CREATE TABLE {tables['entries']} (
+            id INTEGER PRIMARY KEY,
+            conversation_id INTEGER NOT NULL,
+            head INTEGER,
+            commit_seq INTEGER NOT NULL,
+            record TEXT NOT NULL CHECK (json_valid(record))
+        ) STRICT""",
+        f"CREATE INDEX {indexes['entriesByConversation']} "
+        f"ON {tables['entries']} (conversation_id, id DESC)",
+        f"CREATE INDEX {indexes['entryHeadsByConversation']} "
+        f"ON {tables['entries']} (conversation_id, id DESC) WHERE head IS NOT NULL",
+        f"""CREATE TABLE {tables['tasks']} (
+            id INTEGER PRIMARY KEY,
+            conversation_id INTEGER NOT NULL,
+            kind TEXT NOT NULL,
+            status TEXT NOT NULL
+                CHECK (status IN ('pending', 'running', 'waiting', 'completing', 'terminal')),
+            abort_requested INTEGER NOT NULL CHECK (abort_requested IN (0, 1)),
+            background INTEGER NOT NULL CHECK (background IN (0, 1)),
+            record TEXT NOT NULL CHECK (json_valid(record))
+        ) STRICT""",
+        f"CREATE INDEX {indexes['tasksByStatus']} ON {tables['tasks']} (status, id)",
+        f"CREATE INDEX {indexes['tasksByConversation']} ON {tables['tasks']} (conversation_id, id)",
+        f"CREATE INDEX {indexes['tasksByKind']} ON {tables['tasks']} (kind, id)",
+        f"CREATE INDEX {indexes['tasksByAbortRequested']} "
+        f"ON {tables['tasks']} (abort_requested, id)",
+        f"CREATE INDEX {indexes['tasksByBackground']} ON {tables['tasks']} (background, id)",
+        f"""CREATE TABLE {tables['submissions']} (
+            id INTEGER PRIMARY KEY,
+            conversation_id INTEGER NOT NULL,
+            request_id TEXT,
+            status TEXT NOT NULL CHECK (status IN ('queued', 'placed', 'done', 'unanswered')),
+            record TEXT NOT NULL CHECK (json_valid(record))
+        ) STRICT""",
+        f"CREATE INDEX {indexes['submissionsByRequest']} "
+        f"ON {tables['submissions']} (conversation_id, request_id)",
+        f"CREATE INDEX {indexes['submissionsByConversation']} "
+        f"ON {tables['submissions']} (conversation_id, id)",
+        f"CREATE INDEX {indexes['submissionsByStatus']} ON {tables['submissions']} (status, id)",
+        f"""CREATE TABLE {tables['documents']} (
+            id INTEGER PRIMARY KEY,
+            kind TEXT NOT NULL,
+            family INTEGER NOT NULL CHECK (family IN (0, 1)),
+            key_value TEXT NOT NULL,
+            scope_kind TEXT NOT NULL CHECK (scope_kind IN ('session', 'conversation', 'task')),
+            owner_id INTEGER NOT NULL,
+            created_at INTEGER NOT NULL,
+            retired_at INTEGER,
+            record TEXT NOT NULL CHECK (json_valid(record))
+        ) STRICT""",
+        f"""CREATE INDEX {indexes['documentsByAddress']} ON {tables['documents']}
+            (kind, scope_kind, owner_id, family, key_value, created_at DESC, retired_at)""",
+        f"CREATE INDEX {indexes['documentsByScope']} "
+        f"ON {tables['documents']} (scope_kind, owner_id, id)",
+        f"CREATE INDEX {indexes['documentsByScopeKind']} "
+        f"ON {tables['documents']} (scope_kind, owner_id, kind, id)",
+        f"""CREATE TABLE {tables['documentRevisions']} (
+            document_id INTEGER NOT NULL,
+            seq INTEGER NOT NULL,
+            kind TEXT NOT NULL CHECK (kind IN ('base', 'delta')),
+            version INTEGER NOT NULL,
+            content TEXT NOT NULL CHECK (json_valid(content)),
+            PRIMARY KEY (document_id, seq)
+        ) STRICT""",
+        f"CREATE INDEX {indexes['documentRevisionsByKind']} "
+        f"ON {tables['documentRevisions']} (document_id, kind, seq DESC)",
+    )
+    return (SqliteMigration(version=1, statements=initial_schema),)
+
+
+SQLITE_MIGRATIONS = create_sqlite_migrations(DEFAULT_SQLITE_SCHEMA)
+CURRENT_SQLITE_SCHEMA_VERSION = SQLITE_MIGRATIONS[-1].version if SQLITE_MIGRATIONS else 0
+
+
+async def apply_sqlite_migrations(
+    database: SqliteDatabase,
+    migrations: Sequence[SqliteMigration] | None = None,
+) -> None:
+    """Apply all pending schema migrations atomically."""
+
+    await apply_sqlite_migrations_for_schema(
+        database,
+        DEFAULT_SQLITE_SCHEMA,
+        SQLITE_MIGRATIONS if migrations is None else migrations,
+    )
+
+
+async def apply_sqlite_migrations_for_schema(
+    database: SqliteDatabase,
+    schema: SqliteSchema,
+    migrations: Sequence[SqliteMigration] | None = None,
+) -> None:
+    """Apply migrations rendered for a particular schema."""
+
+    if migrations is None:
+        migrations = create_sqlite_migrations(schema)
+    for index, migration in enumerate(migrations):
+        if migration.version != index + 1:
+            raise RuntimeError("Durable SQLite migrations must have contiguous versions starting at 1")
+
+    durable_schema = schema.tables["durableSchema"]
+
+    async def migrate(transaction: SqliteExecutor) -> None:
+        await transaction.exec(
+            f"""CREATE TABLE IF NOT EXISTS {durable_schema} (
+                singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
+                version INTEGER NOT NULL CHECK (version >= 0)
+            ) STRICT"""
+        )
+        await transaction.run(
+            f"INSERT OR IGNORE INTO {durable_schema} (singleton, version) VALUES (1, 0)"
+        )
+        row = await transaction.get(
+            f"SELECT version FROM {durable_schema} WHERE singleton = 1"
+        )
+        if row is None:
+            raise RuntimeError("Durable SQLite schema metadata is missing")
+        current_version = migrations[-1].version if migrations else 0
+        if row["version"] > current_version:
+            raise RuntimeError(
+                f"Durable SQLite schema version {row['version']} is newer than supported "
+                f"version {current_version}"
+            )
+        for migration in migrations:
+            if migration.version <= row["version"]:
+                continue
+            for statement in migration.statements:
+                await transaction.exec(statement)
+            await transaction.run(
+                f"UPDATE {durable_schema} SET version = ? WHERE singleton = 1", migration.version
+            )
+
+    await database.transaction(migrate)
+
+
+__all__ = [
+    "CURRENT_SQLITE_SCHEMA_VERSION",
+    "SQLITE_MIGRATIONS",
+    "SqliteMigration",
+    "apply_sqlite_migrations",
+    "apply_sqlite_migrations_for_schema",
+    "create_sqlite_migrations",
+]

pi_durable/storage/sqlite/posix.py

@@ -0,0 +1,314 @@
+"""Stdlib ``sqlite3`` adapter for the portable SQLite core.
+
+Python replaces the host-specific Node driver with this adapter, as it replaces
+``NodeExecutionEnv`` with :class:`~pi_durable.env.posix.PosixExecutionEnv`. It supplies the
+:class:`~pi_durable.storage.sqlite.database.SqliteDatabase` facade: calls run in call order, a
+transaction holds the connection until its callback settles, and prepared statements are reused
+across ordinary operations and transaction handles.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import sqlite3
+from collections.abc import Awaitable, Callable
+from pathlib import Path
+from typing import Any, NotRequired, TypedDict, TypeVar
+
+from .database import SqliteExecutor, SqliteValue
+from .schema import validate_sqlite_schema_prefix
+from .storage import SqliteStorage, SqliteStorageOptions
+
+T = TypeVar("T")
+
+_DEFAULT_WAL_AUTO_CHECKPOINT_PAGES = 1_000
+_DEFAULT_BUSY_TIMEOUT_MS = 5_000
+
+
+class PosixSqliteDatabaseOptions(TypedDict):
+    """Connection settings for a stdlib-backed SQLite file."""
+
+    wal_auto_checkpoint_pages: NotRequired[int]
+    """SQLite WAL auto-checkpoint threshold in pages; 0 disables it (SQLite default: 1000)."""
+
+    busy_timeout_ms: NotRequired[int]
+    """Time SQLite waits for a competing file lock (SQLite default: 0; here: 5000 ms)."""
+
+
+class PosixSqliteStorageOptions(PosixSqliteDatabaseOptions):
+    """Connection settings plus durable storage options for a stdlib-backed file."""
+
+    prefix: NotRequired[str]
+
+
+class _TransactionScope:
+    """Whether a transaction handle still belongs to a live transaction."""
+
+    __slots__ = ("active",)
+
+    def __init__(self) -> None:
+        self.active = True
+
+
+class _SerialOperationQueue:
+    """Runs operations in call order; an asynchronous operation holds the queue until it settles."""
+
+    __slots__ = ("_tail", "_tasks")
+
+    def __init__(self) -> None:
+        self._tail: asyncio.Future[None] | None = None
+        self._tasks: set[asyncio.Task[None]] = set()
+
+    def run(self, operation: Callable[[], Awaitable[T]]) -> asyncio.Future[T]:
+        loop = asyncio.get_running_loop()
+        result: asyncio.Future[T] = loop.create_future()
+        barrier: asyncio.Future[None] = loop.create_future()
+        previous, self._tail = self._tail, barrier
+
+        async def runner() -> None:
+            if previous is not None:
+                await previous
+            try:
+                value = await operation()
+            except BaseException as error:
+                if not result.done():
+                    result.set_exception(error)
+            else:
+                if not result.done():
+                    result.set_result(value)
+            finally:
+                if not barrier.done():
+                    barrier.set_result(None)
+
+        task = loop.create_task(runner())
+        self._tasks.add(task)
+        task.add_done_callback(self._tasks.discard)
+        return result
+
+
+class _PosixSqliteExecutor:
+    """One statement per ``run``/``get``/``all`` on a shared connection and statement cache."""
+
+    __slots__ = ("_connection", "_statements", "_preparer")
+
+    def __init__(
+        self,
+        connection: sqlite3.Connection,
+        statements: dict[str, sqlite3.Cursor],
+        prepare: Callable[[str], sqlite3.Cursor] | None = None,
+    ) -> None:
+        self._connection = connection
+        self._statements = statements
+        self._preparer = self.prepare if prepare is None else prepare
+
+    def prepare(self, sql: str) -> sqlite3.Cursor:
+        """Return a cursor for ``sql``; a subclass may count preparation misses."""
+
+        return self._connection.cursor()
+
+    def exec(self, sql: str) -> asyncio.Future[None]:
+        return self._run(lambda: self._execute_script(sql))
+
+    def run(self, sql: str, *params: SqliteValue) -> asyncio.Future[None]:
+        def execute() -> None:
+            self._statement(sql).execute(sql, params)
+
+        return self._run(execute)
+
+    def get(self, sql: str, *params: SqliteValue) -> asyncio.Future[dict[str, Any] | None]:
+        def execute() -> dict[str, Any] | None:
+            cursor = self._statement(sql)
+            cursor.execute(sql, params)
+            row = cursor.fetchone()
+            return None if row is None else dict(row)
+
+        return self._run(execute)
+
+    def all(self, sql: str, *params: SqliteValue) -> asyncio.Future[list[dict[str, Any]]]:
+        def execute() -> list[dict[str, Any]]:
+            cursor = self._statement(sql)
+            cursor.execute(sql, params)
+            return [dict(row) for row in cursor.fetchall()]
+
+        return self._run(execute)
+
+    def _execute_script(self, sql: str) -> None:
+        self._connection.executescript(sql)
+
+    def _statement(self, sql: str) -> sqlite3.Cursor:
+        cursor = self._statements.get(sql)
+        if cursor is None:
+            cursor = self._preparer(sql)
+            self._statements[sql] = cursor
+        return cursor
+
+    def _run(self, operation: Callable[[], T]) -> asyncio.Future[T]:
+        raise NotImplementedError
+
+
+class _PosixSqliteTransaction(_PosixSqliteExecutor):
+    """A transaction handle: runs synchronously inside the owning transaction until it settles."""
+
+    __slots__ = ("_scope",)
+
+    def __init__(
+        self,
+        connection: sqlite3.Connection,
+        statements: dict[str, sqlite3.Cursor],
+        prepare: Callable[[str], sqlite3.Cursor],
+        scope: _TransactionScope,
+    ) -> None:
+        super().__init__(connection, statements, prepare)
+        self._scope = scope
+
+    def _execute_script(self, sql: str) -> None:
+        for statement in _complete_statements(sql):
+            self._connection.execute(statement)
+
+    def _run(self, operation: Callable[[], T]) -> asyncio.Future[T]:
+        future: asyncio.Future[T] = asyncio.get_running_loop().create_future()
+        if not self._scope.active:
+            future.set_exception(RuntimeError("SQLite transaction handle is no longer active"))
+            return future
+        try:
+            future.set_result(operation())
+        except BaseException as error:
+            future.set_exception(error)
+        return future
+
+
+class PosixSqliteDatabase(_PosixSqliteExecutor):
+    """``SqliteDatabase`` facade backed by Python's stdlib :mod:`sqlite3`."""
+
+    __slots__ = ("_closing", "_closed", "_queue")
+
+    def __init__(self, connection: sqlite3.Connection) -> None:
+        super().__init__(connection, {})
+        self._queue = _SerialOperationQueue()
+        self._closed = False
+        self._closing: asyncio.Future[None] | None = None
+
+    def transaction(self, callback: Callable[[SqliteExecutor], Awaitable[T]]) -> asyncio.Future[T]:
+        async def run_transaction() -> T:
+            scope = _TransactionScope()
+            transaction = _PosixSqliteTransaction(
+                self._connection, self._statements, self._preparer, scope
+            )
+            self._connection.execute("BEGIN IMMEDIATE")
+            try:
+                result = await callback(transaction)
+                scope.active = False
+                self._connection.execute("COMMIT")
+                return result
+            except BaseException as error:
+                scope.active = False
+                try:
+                    self._connection.execute("ROLLBACK")
+                except Exception as rollback_error:
+                    if isinstance(error, Exception):
+                        raise ExceptionGroup(
+                            "SQLite transaction failed and rollback failed",
+                            [error, rollback_error],
+                        ) from None
+                    raise rollback_error from None
+                raise
+
+        return self._queue.run(run_transaction)
+
+    def close(self) -> asyncio.Future[None]:
+        if self._closing is None:
+            async def close_database() -> None:
+                self._close()
+
+            self._closing = self._queue.run(close_database)
+        return self._closing
+
+    def _close(self) -> None:
+        if self._closed:
+            return
+        self._closed = True
+        self._statements.clear()
+        try:
+            self._connection.execute("PRAGMA wal_checkpoint(TRUNCATE)")
+        finally:
+            self._connection.close()
+
+    def _run(self, operation: Callable[[], T]) -> asyncio.Future[T]:
+        async def call() -> T:
+            return operation()
+
+        return self._queue.run(call)
+
+
+def _complete_statements(sql: str) -> list[str]:
+    """Split SQL text into complete statements, so a transaction handle can run a script."""
+
+    statements: list[str] = []
+    pending = ""
+    for character in sql:
+        pending += character
+        if character == ";" and sqlite3.complete_statement(pending):
+            statements.append(pending)
+            pending = ""
+    if pending.strip():
+        statements.append(pending)
+    return statements
+
+
+async def open_posix_sqlite_database(
+    path: str,
+    options: PosixSqliteDatabaseOptions | None = None,
+) -> PosixSqliteDatabase:
+    """Open and configure a stdlib-backed SQLite database facade."""
+
+    checkpoint_pages = (
+        _DEFAULT_WAL_AUTO_CHECKPOINT_PAGES
+        if options is None
+        else options.get("wal_auto_checkpoint_pages", _DEFAULT_WAL_AUTO_CHECKPOINT_PAGES)
+    )
+    timeout_ms = (
+        _DEFAULT_BUSY_TIMEOUT_MS
+        if options is None
+        else options.get("busy_timeout_ms", _DEFAULT_BUSY_TIMEOUT_MS)
+    )
+    if path != ":memory:":
+        Path(path).parent.mkdir(parents=True, exist_ok=True)
+    connection = sqlite3.connect(path, timeout=timeout_ms / 1000, isolation_level=None)
+    connection.row_factory = sqlite3.Row
+    database = PosixSqliteDatabase(connection)
+    try:
+        await database.exec("PRAGMA journal_mode = WAL")
+        await database.exec("PRAGMA synchronous = NORMAL")
+        await database.exec(f"PRAGMA wal_autocheckpoint = {checkpoint_pages}")
+        return database
+    except BaseException:
+        try:
+            await database.close()
+        except Exception:
+            pass
+        raise
+
+
+async def open_posix_sqlite_storage(
+    path: str,
+    options: PosixSqliteStorageOptions | None = None,
+) -> SqliteStorage:
+    """Open or create file-backed durable storage, optionally under a table prefix."""
+
+    prefix = None if options is None else options.get("prefix")
+    if prefix is not None:
+        validate_sqlite_schema_prefix(prefix)
+    database = await open_posix_sqlite_database(path, options)
+    storage_options: SqliteStorageOptions | None = (
+        None if prefix is None else {"prefix": prefix}
+    )
+    return await SqliteStorage.open(database, storage_options)
+
+
+__all__ = [
+    "PosixSqliteDatabase",
+    "PosixSqliteDatabaseOptions",
+    "PosixSqliteStorageOptions",
+    "open_posix_sqlite_database",
+    "open_posix_sqlite_storage",
+]