pyfect-dev 0.1.0__py3-none-any.whl

pyfect/sql/resolver.py

@@ -0,0 +1,294 @@
+"""Batched SQL requests (Effect's ``effect/sql/SqlResolver``).
+
+A resolver turns the requests made in the same scheduler tick into one
+query: each payload is encoded with the request schema (a payload that
+fails to encode fails its own request), ``execute`` runs once with the
+encoded payloads, and the rows decode with the result schema. Requests
+inside a client's transaction batch only with requests of the same
+transaction::
+
+    get_person = resolver.find_by_id(
+        id=S.Number,
+        result=Person,
+        result_id=lambda person, _row: person.id,
+        execute=lambda ids: sql("SELECT * FROM people WHERE id IN {}", sql.in_(ids)),
+    )
+    person = yield from resolver.request(1, get_person)
+"""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from collections.abc import Callable, Hashable, Sequence
+from typing import Any, Never, cast, overload
+
+from pyfect._core import Effect, _Locally, _MatchCause, _Succeed, _Suspend
+from pyfect.batching import Entry, Request, RequestResolver
+from pyfect.batching import request as make_request
+from pyfect.cause import Cause
+from pyfect.errors import NoSuchElementException
+from pyfect.exit import Failure, Success
+from pyfect.exit import fail as exit_fail
+from pyfect.schema import Array, Codec, SchemaError, decode_unknown_effect, encode_effect
+from pyfect.sql.client import SqlClient, TransactionLevel
+from pyfect.sql.error import ResultLengthMismatch
+
+
+class SqlRequest[In, A, E = Never, R = Never](Request[A, E, R]):
+    """A request carrying ``payload``; requests with equal payloads are
+    equal."""
+
+    __slots__ = ("payload",)
+
+    def __init__(self, payload: In) -> None:
+        self.payload = payload
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, SqlRequest):
+            return False
+        that: SqlRequest[Any, Any, Any, Any] = other  # pyright: ignore[reportUnknownVariableType]
+        return bool(that.payload == self.payload)
+
+    def __hash__(self) -> int:
+        return hash(self.payload)
+
+    def __repr__(self) -> str:
+        return f"SqlRequest({self.payload!r})"
+
+
+type SqlResolver[In, A, E, R] = RequestResolver[SqlRequest[In, A, E, R], E]
+
+
+@overload
+def request[In, A, E, R](payload: In, resolver: SqlResolver[In, A, E, R], /) -> Effect[A, E, R]: ...
+@overload
+def request[In, A, E, R](
+    resolver: SqlResolver[In, A, E, R], /
+) -> Callable[[In], Effect[A, E, R]]: ...
+def request(*args: Any) -> Any:
+    """Make the request of ``payload`` through ``resolver``;
+    ``request(resolver)`` is the function of the payload."""
+    if len(args) == 1:
+        resolver: SqlResolver[Any, Any, Any, Any] = args[0]
+
+        def make(payload: object) -> Effect[Any, Any, Any]:
+            return _request(payload, resolver)
+
+        return make
+    return _request(args[0], args[1])
+
+
+def _request(payload: object, resolver: SqlResolver[Any, Any, Any, Any]) -> Effect[Any, Any, Any]:
+    req: SqlRequest[Any, Any, Any, Any] = SqlRequest(payload)
+    return make_request(req, resolver)
+
+
+def _transaction_key(entry: Entry[Any]) -> Hashable:
+    """The transaction the request was made in (by identity), or ``None``."""
+    context = entry.context
+    found, client = context.lookup(SqlClient)
+    if not found:
+        return None
+    found, level = context.lookup(client.transaction_service)
+    return cast("TransactionLevel", level) if found else None
+
+
+type _Entries = Sequence[Entry[SqlRequest[Any, Any, Any, Any]]]
+
+
+def _in_context[A, E](effect: Effect[A, E, Any], entry: Entry[Any]) -> Effect[A, E]:
+    context = entry.context
+    return _Locally(effect, lambda _: context)
+
+
+def _fail_entry(entry: Entry[Any], cause: Cause[SchemaError]) -> None:
+    entry.complete_unsafe(Failure(cause))
+
+
+def _encode_each(
+    entries: _Entries,
+    schema: Codec[Any, Any, Any, Any],
+    fail: Callable[[Entry[Any], Cause[SchemaError]], None] = _fail_entry,
+) -> Effect[tuple[list[object], list[Entry[Any]]]]:
+    """Each entry's encoded payload, and the entries that encoded; those
+    that did not are failed with the schema error (by ``fail``)."""
+    encode = encode_effect(schema)
+    inputs: list[object] = []
+    encoded: list[Entry[Any]] = []
+
+    def one(entry: Entry[Any]) -> Effect[None]:
+        def failed(cause: Cause[SchemaError]) -> Effect[None]:
+            fail(entry, cause)
+            return _Succeed(None)
+
+        def succeeded(value: object) -> Effect[None]:
+            inputs.append(value)
+            encoded.append(entry)
+            return _Succeed(None)
+
+        return _MatchCause(_in_context(encode(entry.request.payload), entry), failed, succeeded)
+
+    run: Effect[None] = _Succeed(None)
+    for entry in entries:
+        run = run.and_then(_Suspend(lambda entry=entry: one(entry)))
+    return run.map(lambda _: (inputs, encoded))
+
+
+def _decode_rows(
+    result: Codec[Any, Any, Any, Any], rows: Sequence[object], entry: Entry[Any]
+) -> Effect[tuple[Any, ...], SchemaError]:
+    return _in_context(decode_unknown_effect(Array(result))(rows), entry)
+
+
+def ordered[In, A, E = Never, R = Never](
+    *,
+    request: Codec[In, Any, Any, Any],
+    result: Codec[A, Any, Any, Any],
+    execute: Callable[[Sequence[Any]], Effect[Sequence[object], E, R]],
+) -> SqlResolver[In, A, E | ResultLengthMismatch | SchemaError, R]:
+    """``execute`` returns one row per request, in the order of the
+    requests; a different number of rows fails every request with
+    ``ResultLengthMismatch``."""
+
+    def resolve(entries: _Entries, _key: Hashable) -> Effect[None, Any]:
+        def run(encoded: tuple[list[object], list[Entry[Any]]]) -> Effect[None, Any]:
+            inputs, encoded_entries = encoded
+            if not inputs:
+                return _Succeed(None)
+
+            def check(rows: Sequence[object]) -> Effect[None, Any]:
+                if len(rows) != len(inputs):
+                    from pyfect.effect import fail
+
+                    return fail(ResultLengthMismatch(expected=len(inputs), actual=len(rows)))
+                return _decode_rows(result, rows, entries[0]).map(
+                    lambda values: _complete_all(encoded_entries, values)
+                )
+
+            return _in_context(execute(inputs), entries[0]).flat_map(check)
+
+        return _encode_each(entries, request).flat_map(run)
+
+    return RequestResolver.make_grouped(key=_transaction_key, resolver=resolve)
+
+
+def _complete_all(entries: Sequence[Entry[Any]], values: Sequence[object]) -> None:
+    for entry, value in zip(entries, values, strict=True):
+        entry.complete_unsafe(Success(value))
+
+
+_NO_SUCH_ELEMENT = exit_fail(NoSuchElementException())
+
+
+def grouped[In, A, K: Hashable, Row, E = Never, R = Never](
+    *,
+    request: Codec[In, Any, Any, Any],
+    request_group_key: Callable[[In], K],
+    result: Codec[A, Any, Any, Any],
+    result_group_key: Callable[[A, Row], K],
+    execute: Callable[[Sequence[Any]], Effect[Sequence[Row], E, R]],
+) -> SqlResolver[In, tuple[A, ...], E | SchemaError | NoSuchElementException, R]:
+    """Each request gets the results whose ``result_group_key`` equals its
+    ``request_group_key`` (at least one; none fails with
+    ``NoSuchElementException``)."""
+
+    def resolve(entries: _Entries, _key: Hashable) -> Effect[None, Any]:
+        def run(encoded: tuple[list[object], list[Entry[Any]]]) -> Effect[None, Any]:
+            inputs, _ = encoded
+            if not inputs:
+                return _Succeed(None)
+
+            def complete(rows: Sequence[Row], values: Sequence[A]) -> None:
+                groups: dict[K, list[A]] = {}
+                for value, row in zip(values, rows, strict=True):
+                    groups.setdefault(result_group_key(value, row), []).append(value)
+                for entry in entries:
+                    group = groups.get(request_group_key(entry.request.payload))
+                    entry.complete_unsafe(
+                        _NO_SUCH_ELEMENT if group is None else Success(tuple(group))
+                    )
+
+            def decode(rows: Sequence[Row]) -> Effect[None, Any]:
+                return _decode_rows(result, rows, entries[0]).map(
+                    lambda values: complete(rows, values)
+                )
+
+            return _in_context(execute(inputs), entries[0]).flat_map(decode)
+
+        return _encode_each(entries, request).flat_map(run)
+
+    return RequestResolver.make_grouped(key=_transaction_key, resolver=resolve)
+
+
+def find_by_id[Id: Hashable, A, Row, E = Never, R = Never](
+    *,
+    id: Codec[Id, Any, Any, Any],
+    result: Codec[A, Any, Any, Any],
+    result_id: Callable[[A, Row], Id],
+    execute: Callable[[Sequence[Any]], Effect[Sequence[Row], E, R]],
+) -> SqlResolver[Id, A, E | SchemaError | NoSuchElementException, R]:
+    """Each request gets the result whose ``result_id`` is its id (none
+    fails with ``NoSuchElementException``). Equal ids are queried once."""
+
+    def resolve(entries: _Entries, _key: Hashable) -> Effect[None, Any]:
+        by_id: dict[Hashable, list[Entry[Any]]] = {}
+        for entry in entries:
+            by_id.setdefault(entry.request.payload, []).append(entry)
+        firsts = [same[0] for same in by_id.values()]
+
+        def run(encoded: tuple[list[object], list[Entry[Any]]]) -> Effect[None, Any]:
+            inputs, _ = encoded
+            if not inputs:
+                return _Succeed(None)
+
+            def complete(rows: Sequence[Row], values: Sequence[A]) -> None:
+                for value, row in zip(values, rows, strict=True):
+                    same = by_id.pop(result_id(value, row), None)
+                    for entry in same or ():
+                        entry.complete_unsafe(Success(value))
+                for same in by_id.values():
+                    for entry in same:
+                        entry.complete_unsafe(_NO_SUCH_ELEMENT)
+
+            def decode(rows: Sequence[Row]) -> Effect[None, Any]:
+                return _decode_rows(result, rows, entries[0]).map(
+                    lambda values: complete(rows, values)
+                )
+
+            return _in_context(execute(inputs), entries[0]).flat_map(decode)
+
+        def fail_all(entry: Entry[Any], cause: Cause[SchemaError]) -> None:
+            # Requests for the same id share its encoding failure.
+            for same in by_id.pop(entry.request.payload):
+                same.complete_unsafe(Failure(cause))
+
+        return _encode_each(firsts, id, fail_all).flat_map(run)
+
+    return RequestResolver.make_grouped(key=_transaction_key, resolver=resolve)
+
+
+def void[In, E = Never, R = Never](
+    *,
+    request: Codec[In, Any, Any, Any],
+    execute: Callable[[Sequence[Any]], Effect[object, E, R]],
+) -> SqlResolver[In, None, E | SchemaError, R]:
+    """Requests without a result: ``execute`` runs them together."""
+
+    def resolve(entries: _Entries, _key: Hashable) -> Effect[None, Any]:
+        def run(encoded: tuple[list[object], list[Entry[Any]]]) -> Effect[None, Any]:
+            inputs, _ = encoded
+            if not inputs:
+                return _Succeed(None)
+
+            def complete(_: object) -> None:
+                for entry in entries:
+                    entry.complete_unsafe(Success(None))
+
+            return _in_context(execute(inputs), entries[0]).map(complete)
+
+        return _encode_each(entries, request).flat_map(run)
+
+    return RequestResolver.make_grouped(key=_transaction_key, resolver=resolve)
+
+
+__all__ = ["SqlRequest", "SqlResolver", "find_by_id", "grouped", "ordered", "request", "void"]

pyfect/sql/result.py

@@ -0,0 +1,24 @@
+"""What a driver's raw result (``Statement.raw``) says about a statement
+that changes rows, read the same way whatever the driver."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class RowCount(Protocol):
+    """A raw result that counts the rows it changed (the MySQL driver's
+    ``ResultSetHeader``)."""
+
+    @property
+    def affected_rows(self) -> int: ...
+
+
+def affected_rows(result: object) -> int:
+    """How many rows the statement of ``result`` changed; 0 when its
+    driver's result does not count them."""
+    return result.affected_rows if isinstance(result, RowCount) else 0
+
+
+__all__ = ["RowCount", "affected_rows"]

pyfect/sql/schema.py

@@ -0,0 +1,116 @@
+"""Queries typed by schemas (Effect's ``effect/sql/SqlSchema``).
+
+Each function takes the request schema, the result schema and ``execute``,
+and returns the query as a function of the request: the request is encoded
+before ``execute`` runs with it, and the rows it returns are decoded::
+
+    find_person = sql_schema.find_one(
+        request=S.Number,
+        result=Person,
+        execute=lambda id: sql("SELECT * FROM people WHERE id = {}", id),
+    )
+    person = yield from find_person(1)
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from typing import Any, Never
+
+from pyfect._core import Effect
+from pyfect.effect import fail, succeed
+from pyfect.errors import NoSuchElementException
+from pyfect.option import Option, Some
+from pyfect.schema import Array, Codec, SchemaError, decode_unknown_effect, encode_effect
+
+
+def find_all[In, A, E = Never, R = Never](
+    *,
+    request: Codec[In, Any, Any, Any],
+    result: Codec[A, Any, Any, Any],
+    execute: Callable[[Any], Effect[Sequence[object], E, R]],
+) -> Callable[[In], Effect[list[A], E | SchemaError, R]]:
+    """Every row, decoded."""
+    encode = encode_effect(request)
+    decode = decode_unknown_effect(Array(result))
+
+    def query(value: In) -> Effect[list[A], E | SchemaError, R]:
+        return encode(value).flat_map(execute).flat_map(decode).map(list)
+
+    return query
+
+
+def find_non_empty[In, A, E = Never, R = Never](
+    *,
+    request: Codec[In, Any, Any, Any],
+    result: Codec[A, Any, Any, Any],
+    execute: Callable[[Any], Effect[Sequence[object], E, R]],
+) -> Callable[[In], Effect[list[A], E | SchemaError | NoSuchElementException, R]]:
+    """Every row, decoded; no rows fails with ``NoSuchElementException``."""
+    find = find_all(request=request, result=result, execute=execute)
+
+    def non_empty(rows: list[A]) -> Effect[list[A], NoSuchElementException]:
+        return succeed(rows) if rows else fail(NoSuchElementException())
+
+    def query(value: In) -> Effect[list[A], E | SchemaError | NoSuchElementException, R]:
+        return find(value).flat_map(non_empty)
+
+    return query
+
+
+def void[In, E = Never, R = Never](
+    *,
+    request: Codec[In, Any, Any, Any],
+    execute: Callable[[Any], Effect[object, E, R]],
+) -> Callable[[In], Effect[None, E | SchemaError, R]]:
+    """Runs ``execute``, ignoring its result."""
+    encode = encode_effect(request)
+
+    def query(value: In) -> Effect[None, E | SchemaError, R]:
+        return encode(value).flat_map(execute).as_void()
+
+    return query
+
+
+def find_one[In, A, E = Never, R = Never](
+    *,
+    request: Codec[In, Any, Any, Any],
+    result: Codec[A, Any, Any, Any],
+    execute: Callable[[Any], Effect[Sequence[object], E, R]],
+) -> Callable[[In], Effect[A, E | SchemaError | NoSuchElementException, R]]:
+    """The first row, decoded; no rows fails with
+    ``NoSuchElementException``."""
+    encode = encode_effect(request)
+    decode = decode_unknown_effect(result)
+
+    def first(rows: Sequence[object]) -> Effect[A, SchemaError | NoSuchElementException]:
+        return decode(rows[0]) if rows else fail(NoSuchElementException())
+
+    def query(value: In) -> Effect[A, E | SchemaError | NoSuchElementException, R]:
+        return encode(value).flat_map(execute).flat_map(first)
+
+    return query
+
+
+def find_one_option[In, A, E = Never, R = Never](
+    *,
+    request: Codec[In, Any, Any, Any],
+    result: Codec[A, Any, Any, Any],
+    execute: Callable[[Any], Effect[Sequence[object], E, R]],
+) -> Callable[[In], Effect[Option[A], E | SchemaError, R]]:
+    """The first row decoded, or ``None`` for no rows."""
+    encode = encode_effect(request)
+    decode = decode_unknown_effect(result)
+
+    def first(rows: Sequence[object]) -> Effect[Option[A], SchemaError]:
+        if not rows:
+            return succeed(None)
+        return decode(rows[0]).map(Some)
+
+    def query(value: In) -> Effect[Option[A], E | SchemaError, R]:
+        return encode(value).flat_map(execute).flat_map(first)
+
+    return query
+
+
+__all__ = ["find_all", "find_non_empty", "find_one", "find_one_option", "void"]

pyfect/sql/sqlite/__init__.py

@@ -0,0 +1,26 @@
+"""SQLite on the standard library's ``sqlite3`` (Effect's
+``@effect/sql-sqlite-node``)."""
+
+from pyfect.sql.sqlite.client import (
+    BackupMetadata,
+    RunResult,
+    SqliteClient,
+    SqliteClientConfig,
+    SqliteClientService,
+    SqliteConnection,
+    layer,
+    layer_config,
+    make,
+)
+
+__all__ = [
+    "BackupMetadata",
+    "RunResult",
+    "SqliteClient",
+    "SqliteClientConfig",
+    "SqliteClientService",
+    "SqliteConnection",
+    "layer",
+    "layer_config",
+    "make",
+]

pyfect/sql/sqlite/_connection.py

@@ -0,0 +1,230 @@
+"""A SQLite connection on its worker thread (the connection of Effect's
+``@effect/sql-sqlite-node``)."""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+import sqlite3
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+from urllib.parse import quote, urlsplit, urlunsplit
+
+from pyfect._core import Effect, _Succeed, _Suspend, _Sync
+from pyfect.sql.connection import Row, TransformRows, ValueRow
+from pyfect.sql.error import SqlError, classify_sqlite_error
+from pyfect.sql.sqlite._worker import Worker
+
+if TYPE_CHECKING:
+    from pyfect.stream import Stream
+
+
+@dataclass(frozen=True, slots=True)
+class RunResult:
+    """What ``raw`` gives for a statement without result columns."""
+
+    changes: int
+    last_insert_rowid: int
+
+
+@dataclass(frozen=True, slots=True)
+class BackupMetadata:
+    total_pages: int
+    remaining_pages: int
+
+
+def _catch(message: str, operation: str) -> Callable[[Exception], SqlError]:
+    return lambda cause: SqlError(
+        reason=classify_sqlite_error(cause, message=message, operation=operation)
+    )
+
+
+_catch_execute = _catch("Failed to execute statement", "execute")
+
+
+def _rows(cursor: sqlite3.Cursor) -> list[Row]:
+    if cursor.description is None:
+        return []
+    names = [column[0] for column in cursor.description]
+    return [dict(zip(names, row, strict=True)) for row in cursor.fetchall()]
+
+
+def _changes(db: sqlite3.Connection) -> RunResult:
+    changes, rowid = db.execute("SELECT changes(), last_insert_rowid()").fetchone()
+    return RunResult(changes, rowid)
+
+
+class SqliteConnection:
+    """Runs statements on one ``sqlite3`` connection, on its worker thread.
+
+    ``sqlite3`` keeps a cache of prepared statements (``cached_statements``)
+    and has no other way to run one, so the prepared and unprepared calls
+    run alike."""
+
+    def __init__(self, db: sqlite3.Connection, worker: Worker) -> None:
+        self._db = db
+        self._worker = worker
+
+    def is_transaction(self) -> bool:
+        return self._db.in_transaction
+
+    def _call[A](
+        self,
+        f: Callable[[sqlite3.Connection], A],
+        catch: Callable[[Exception], SqlError] = _catch_execute,
+    ) -> Effect[A, SqlError]:
+        db = self._db
+        return self._worker.call(lambda: f(db), catch)
+
+    def _execute(self, sql: str, params: Sequence[object]) -> Effect[list[Row], SqlError]:
+        values = tuple(params)
+        return self._call(lambda db: _rows(db.execute(sql, values)))
+
+    def execute(
+        self, sql: str, params: Sequence[object], transform_rows: TransformRows | None, /
+    ) -> Effect[Sequence[Row], SqlError]:
+        rows = self._execute(sql, params)
+        return rows if transform_rows is None else rows.map(transform_rows)
+
+    def execute_unprepared(
+        self, sql: str, params: Sequence[object], transform_rows: TransformRows | None, /
+    ) -> Effect[Sequence[Row], SqlError]:
+        return self.execute(sql, params, transform_rows)
+
+    def execute_raw(self, sql: str, params: Sequence[object], /) -> Effect[object, SqlError]:
+        """Rows, or a ``RunResult`` for a statement without result
+        columns."""
+        values = tuple(params)
+
+        def run(db: sqlite3.Connection) -> object:
+            cursor = db.execute(sql, values)
+            if cursor.description is None:
+                return _changes(db)
+            return _rows(cursor)
+
+        return self._call(run)
+
+    def execute_values(
+        self, sql: str, params: Sequence[object], /
+    ) -> Effect[Sequence[ValueRow], SqlError]:
+        values = tuple(params)
+
+        def run(db: sqlite3.Connection) -> list[ValueRow]:
+            cursor = db.execute(sql, values)
+            if cursor.description is None:
+                return []
+            return [tuple(row) for row in cursor.fetchall()]
+
+        return self._call(run)
+
+    def execute_values_unprepared(
+        self, sql: str, params: Sequence[object], /
+    ) -> Effect[Sequence[ValueRow], SqlError]:
+        return self.execute_values(sql, params)
+
+    def execute_stream(
+        self, sql: str, params: Sequence[object], transform_rows: TransformRows | None, /
+    ) -> Stream[Row, SqlError]:
+        from pyfect import stream
+
+        return stream.die(NotImplementedError("executeStream not implemented"))
+
+    def backup(self, destination: str) -> Effect[BackupMetadata, SqlError]:
+        """Copy the database to the file ``destination``."""
+
+        def run(db: sqlite3.Connection) -> BackupMetadata:
+            pages = [0]
+
+            def progress(_status: int, _remaining: int, total: int) -> None:
+                pages[0] = total
+
+            target = sqlite3.connect(destination)
+            try:
+                db.backup(target, progress=progress)
+            finally:
+                target.close()
+            return BackupMetadata(pages[0], 0)
+
+        return self._call(run, _catch("Failed to backup database", "backup"))
+
+    def load_extension(self, path: str) -> Effect[None, SqlError]:
+        """Load the SQLite extension at ``path`` (fails where Python's
+        ``sqlite3`` was built without extension loading)."""
+
+        def run(db: sqlite3.Connection) -> None:
+            enable: Any = getattr(db, "enable_load_extension", None)
+            if enable is None:
+                raise sqlite3.NotSupportedError("extension loading is not supported")
+            enable(True)
+            try:
+                db.load_extension(path)
+            finally:
+                enable(False)
+
+        return self._call(run, _catch("Failed to load extension", "loadExtension"))
+
+    def exec_config(self, sql: str) -> Effect[None, SqlError]:
+        """Run a configuration statement, failing as a connect error."""
+
+        def run(db: sqlite3.Connection) -> None:
+            db.execute(sql).fetchall()
+
+        return self._call(run, _catch("Failed to configure database", "connect"))
+
+    def close(self) -> Effect[None]:
+        worker = self._worker
+
+        def run(db: sqlite3.Connection) -> None:
+            db.close()
+
+        def stop(_: object) -> Effect[None]:
+            worker.shutdown()
+            return _Succeed(None)
+
+        return self._call(run).or_die().flat_map(stop)
+
+
+def _target(filename: str, readonly: bool) -> tuple[str, bool]:
+    """What ``sqlite3.connect`` opens for ``filename``, and whether it is a
+    URI. A ``file:`` URI is opened as one (as ``node:sqlite`` does); a
+    readonly client opens any file through a URI with ``mode=ro`` (the
+    ``SQLITE_OPEN_READONLY`` flag ``sqlite3`` cannot pass)."""
+    is_uri = filename.startswith("file:")
+    if not readonly:
+        return filename, is_uri
+    if not is_uri:
+        return f"file:{quote(filename)}?mode=ro", True
+    parts = urlsplit(filename)
+    params = [p for p in parts.query.split("&") if p and not p.startswith("mode=")]
+    return urlunsplit(parts._replace(query="&".join([*params, "mode=ro"]))), True
+
+
+def open_connection(
+    filename: str, *, readonly: bool, prepare_cache_size: int
+) -> Effect[SqliteConnection, SqlError]:
+    """Open ``filename`` (a path, ``:memory:`` or a ``file:`` URI) on a new
+    worker thread."""
+    target, uri = _target(filename, readonly)
+
+    def connect() -> sqlite3.Connection:
+        return sqlite3.connect(
+            target,
+            timeout=0,
+            isolation_level=None,
+            check_same_thread=False,
+            cached_statements=max(prepare_cache_size, 0),
+            uri=uri,
+        )
+
+    def body() -> Effect[SqliteConnection, SqlError]:
+        worker = Worker()
+        return (
+            worker.call(connect, _catch("Failed to open database", "connect"))
+            .map(lambda db: SqliteConnection(db, worker))
+            .tap_error(lambda _: _Sync(worker.shutdown))
+        )
+
+    return _Suspend(body)
+
+
+__all__ = ["BackupMetadata", "RunResult", "SqliteConnection", "open_connection"]