pyfect-dev 0.1.0__py3-none-any.whl

pyfect/sql/model.py

@@ -0,0 +1,324 @@
+"""Repositories of models (Effect's ``effect/sql/SqlModel``): insert,
+update, find and delete a ``Model.Class``'s rows::
+
+    repo = yield from sql_model.make_repository(
+        User, table_name="users", span_prefix="UserRepository", id_column="id"
+    )
+    user = yield from repo.insert(User.insert.make({"name": "Ada"}))  # a User
+
+``insert`` and ``update`` take the model's ``insert`` / ``update`` variant
+(the TypedDicts given to ``Model.Class``) and return the row as the model.
+``find_by_id`` and ``delete`` take the id, encoded with the id field's
+schema (pyright cannot read an attribute's type from a column name, so it
+is checked there). With ``soft_delete_column``, ``delete`` sets that
+column to ``CURRENT_TIMESTAMP`` and the reads skip rows where it is set.
+``make_resolvers`` gives the same operations as batched resolvers.
+
+Requests run against the dialect's SQL: ``INSERT ... RETURNING *`` (and
+``UPDATE ... RETURNING *``), or for MySQL the statement followed by a
+``SELECT`` of the row.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Hashable, Mapping, Sequence
+from dataclasses import dataclass
+from typing import Any, Never, Protocol, TypeVar, cast
+
+from pyfect._concurrency import for_each
+from pyfect._core import Effect
+from pyfect.effect import catch_tag, die
+from pyfect.errors import NoSuchElementException
+from pyfect.schema import Codec, SchemaError
+from pyfect.schema.model import ModelVariants
+from pyfect.sql import resolver as sql_resolver
+from pyfect.sql import schema as sql_schema
+from pyfect.sql.client import SqlClient, SqlClientService
+from pyfect.sql.error import ResultLengthMismatch, SqlError
+from pyfect.sql.resolver import SqlResolver
+from pyfect.sql.statement import Fragment, Identifier, Statement
+
+A_co = TypeVar("A_co", covariant=True)
+I_co = TypeVar("I_co", covariant=True)
+U_co = TypeVar("U_co", covariant=True)
+
+
+class ModelType(Protocol[A_co, I_co, U_co]):
+    """A ``Model.Class``: its rows are ``A``, its insert variant ``I`` and
+    its update variant ``U``."""
+
+    def __model_variants__(self) -> ModelVariants[A_co, I_co, U_co]: ...
+
+
+@dataclass(frozen=True, slots=True)
+class Repository[A, In, Up]:
+    """A model's table operations (Effect's ``makeRepository`` result)."""
+
+    insert: Callable[[In], Effect[A, SchemaError | SqlError]]
+    insert_void: Callable[[In], Effect[None, SchemaError | SqlError]]
+    update: Callable[[Up], Effect[A, SchemaError | SqlError]]
+    update_void: Callable[[Up], Effect[None, SchemaError | SqlError]]
+    find_by_id: Callable[[object], Effect[A, NoSuchElementException | SchemaError | SqlError]]
+    delete: Callable[[object], Effect[None, SchemaError | SqlError]]
+
+
+@dataclass(frozen=True, slots=True)
+class Resolvers[A, In]:
+    """A model's table operations as batched resolvers (Effect's
+    ``makeResolvers`` result); run one with ``sql.resolver.request``."""
+
+    insert: SqlResolver[In, A, ResultLengthMismatch | SchemaError | SqlError, Any]
+    insert_void: SqlResolver[In, None, SchemaError | SqlError, Any]
+    find_by_id: SqlResolver[Hashable, A, NoSuchElementException | SchemaError | SqlError, Any]
+    delete: SqlResolver[Hashable, None, SchemaError | SqlError, Any]
+
+
+@dataclass(frozen=True, slots=True)
+class _Table:
+    """A model's table, as the operations write it."""
+
+    sql: SqlClientService
+    model: Any
+    table: str
+    id_column: str
+    soft_delete_column: str | None
+
+    @property
+    def name(self) -> Identifier:
+        return self.sql.identifier(self.table)
+
+    @property
+    def id(self) -> Identifier:
+        return self.sql.identifier(self.id_column)
+
+    def live(self, where: Fragment) -> Fragment:
+        """``where``, and the row not soft-deleted."""
+        if self.soft_delete_column is None:
+            return where
+        deleted = self.sql("{} is null", self.sql.identifier(self.soft_delete_column))
+        return self.sql.and_([where, deleted])
+
+    def id_schema(self) -> Codec[Any, Any, Any, Any]:
+        return self.model.fields()[self.id_column]
+
+
+@dataclass(frozen=True, slots=True)
+class _Columns:
+    """A model's table and columns, checked against its variants when
+    ``make_repository`` / ``make_resolvers`` is called."""
+
+    model: Any
+    table: str
+    id_column: str
+    soft_delete_column: str | None
+
+    def on(self, sql: SqlClientService) -> _Table:
+        return _Table(sql, self.model, self.table, self.id_column, self.soft_delete_column)
+
+
+def _columns(
+    variants: ModelVariants[Any, Any, Any],
+    table_name: str,
+    id_column: str,
+    soft_delete_column: str | None,
+) -> _Columns:
+    """Effect checks ``id_column`` against the update variant's keys at
+    compile time; pyright has no ``keyof`` for a TypedDict, so it is checked
+    here, before any effect runs."""
+    model: Any = variants.model
+    selected = model.fields()
+    update = variants.update.fields
+    if id_column not in selected or id_column not in update:
+        hint = (
+            " (a GeneratedByDb field is in select and json only: declare the id with"
+            " Model.field_only(['select', 'update', 'json'])(...))"
+            if id_column in selected
+            else ""
+        )
+        raise ValueError(
+            f"{model.__name__}: id_column {id_column!r} must be a field of the select and"
+            f" update variants; the 'update' variant has: {', '.join(map(repr, update))}{hint}"
+        )
+    if soft_delete_column is not None and soft_delete_column not in selected:
+        raise ValueError(f"{model.__name__} has no {soft_delete_column!r} field")
+    return _Columns(model, table_name, id_column, soft_delete_column)
+
+
+def make_repository[A, In, Up](
+    model: ModelType[A, In, Up],
+    *,
+    table_name: str,
+    span_prefix: str,
+    id_column: str,
+    soft_delete_column: str | None = None,
+) -> Effect[Repository[A, In, Up], Never, SqlClient]:
+    """A repository of ``model`` on ``table_name`` (Effect's
+    ``makeRepository``); spans are named ``<span_prefix>.insert`` and so on.
+    ``id_column`` must be a field of the ``select`` and ``update`` variants
+    (``ValueError`` when called)."""
+    variants = model.__model_variants__()
+    columns = _columns(variants, table_name, id_column, soft_delete_column)
+
+    def build(sql: SqlClientService) -> Repository[A, In, Up]:
+        return _repository(columns.on(sql), variants, span_prefix)
+
+    return SqlClient().map(build)
+
+
+def _returning_one(t: _Table, statement: Fragment, select_where: Fragment) -> Effect[Any, SqlError]:
+    """The statement's row: ``RETURNING *``, or a second ``SELECT`` on MySQL."""
+    sql = t.sql
+
+    def mysql() -> Effect[Any, SqlError]:
+        both = sql("{}; select * from {} where {};", statement, t.name, t.live(select_where))
+        return both.unprepared.map(lambda results: results[1])
+
+    return sql.on_dialect_or_else(mysql=mysql, or_else=lambda: sql("{} returning *", statement))
+
+
+def _repository[A, In, Up](
+    t: _Table, variants: ModelVariants[A, In, Up], prefix: str
+) -> Repository[A, In, Up]:
+    sql = t.sql
+    model = variants.model
+
+    def insert_statement(row: Mapping[str, object]) -> Statement[Any]:
+        return sql("insert into {} {}", t.name, sql.insert(row))
+
+    def update_statement(row: Mapping[str, object]) -> Statement[Any]:
+        where = t.live(sql("{} = {}", t.id, row[t.id_column]))
+        return sql("update {} set {} where {}", t.name, sql.update(row, [t.id_column]), where)
+
+    def by_id(id: object) -> Fragment:
+        return t.live(sql("{} = {}", t.id, id))
+
+    insert_one = sql_schema.find_one(
+        request=variants.insert,
+        result=model,
+        execute=lambda row: _returning_one(
+            t, insert_statement(row), sql("{} = LAST_INSERT_ID()", t.id)
+        ),
+    )
+    insert_void = sql_schema.void(request=variants.insert, execute=insert_statement)
+    update_one = sql_schema.find_one(
+        request=variants.update,
+        result=model,
+        execute=lambda row: _returning_one(t, update_statement(row), by_id(row[t.id_column])),
+    )
+    update_void = sql_schema.void(request=variants.update, execute=update_statement)
+    find_one = sql_schema.find_one(
+        request=t.id_schema(),
+        result=model,
+        execute=lambda id: sql("select * from {} where {}", t.name, by_id(id)),
+    )
+
+    def delete_statement(id: object) -> Statement[Any]:
+        if t.soft_delete_column is None:
+            return sql("delete from {} where {} = {}", t.name, t.id, id)
+        column = sql.identifier(t.soft_delete_column)
+        return sql("update {} set {} = CURRENT_TIMESTAMP where {}", t.name, column, by_id(id))
+
+    delete_one = sql_schema.void(request=t.id_schema(), execute=delete_statement)
+
+    def span(name: str, **attributes: object) -> Callable[[Effect[Any, Any]], Effect[Any, Any]]:
+        def traced(effect: Effect[Any, Any]) -> Effect[Any, Any]:
+            return effect.with_span(
+                f"{prefix}.{name}", attributes=attributes, capture_stack_trace=False
+            )
+
+        return traced
+
+    def id_of(row: object) -> object:
+        return cast("Mapping[str, object]", row)[t.id_column]
+
+    return Repository(
+        insert=lambda value: span("insert")(_die_on_missing(insert_one(value))),
+        insert_void=lambda value: span("insertVoid")(insert_void(value)),
+        update=lambda value: span("update", id=id_of(value))(_die_on_missing(update_one(value))),
+        update_void=lambda value: span("updateVoid", id=id_of(value))(update_void(value)),
+        find_by_id=lambda id: span("findById", id=id)(find_one(id)),
+        delete=lambda id: span("delete", id=id)(delete_one(id)),
+    )
+
+
+def _die_on_missing[A, E](effect: Effect[A, E | NoSuchElementException]) -> Effect[A, E]:
+    """No row back from an insert or update is a defect, as in Effect."""
+    return effect.pipe(catch_tag(NoSuchElementException, die))
+
+
+def make_resolvers[A, In, Up](
+    model: ModelType[A, In, Up],
+    *,
+    table_name: str,
+    span_prefix: str,
+    id_column: str,
+    soft_delete_column: str | None = None,
+) -> Effect[Resolvers[A, In], Never, SqlClient]:
+    """``make_repository``'s insert, insert-without-result, find and delete
+    as batched resolvers (Effect's ``makeResolvers``): the requests of one
+    scheduler tick (within one transaction) run as one statement."""
+    variants = model.__model_variants__()
+    columns = _columns(variants, table_name, id_column, soft_delete_column)
+
+    def build(sql: SqlClientService) -> Resolvers[A, In]:
+        return _resolvers(columns.on(sql), variants, span_prefix)
+
+    return SqlClient().map(build)
+
+
+def _resolvers[A, In](
+    t: _Table, variants: ModelVariants[A, In, Any], prefix: str
+) -> Resolvers[A, In]:
+    sql = t.sql
+
+    def insert_rows(rows: Sequence[Mapping[str, object]]) -> Effect[Sequence[object], SqlError]:
+        def mysql() -> Effect[Sequence[object], SqlError]:
+            def one(row: Mapping[str, object]) -> Effect[object, SqlError]:
+                statement = sql("insert into {} {}", t.name, sql.insert(row))
+                where = sql("{} = LAST_INSERT_ID()", t.id)
+                return _returning_one(t, statement, where).map(lambda rows: rows[0])
+
+            return for_each(rows, one, concurrency=10)
+
+        return sql.on_dialect_or_else(
+            mysql=mysql,
+            or_else=lambda: sql("insert into {} {}", t.name, sql.insert(rows).returning("*")),
+        )
+
+    def where_ids(ids: Sequence[object]) -> Fragment:
+        return t.live(sql.in_(t.id_column, ids))
+
+    def delete_rows(ids: Sequence[object]) -> Effect[object, SqlError]:
+        if t.soft_delete_column is None:
+            return sql("delete from {} where {}", t.name, sql.in_(t.id_column, ids))
+        column = sql.identifier(t.soft_delete_column)
+        return sql("update {} set {} = CURRENT_TIMESTAMP where {}", t.name, column, where_ids(ids))
+
+    id_column = t.id_column
+
+    def result_id(result: Any, _row: object) -> Hashable:
+        return getattr(result, id_column)
+
+    insert = sql_resolver.ordered(
+        request=variants.insert, result=variants.model, execute=insert_rows
+    )
+    insert_void = sql_resolver.void(
+        request=variants.insert,
+        execute=lambda rows: sql("insert into {} {}", t.name, sql.insert(rows)),
+    )
+    find_by_id = sql_resolver.find_by_id(
+        id=t.id_schema(),
+        result=variants.model,
+        result_id=result_id,
+        execute=lambda ids: sql("select * from {} where {}", t.name, where_ids(ids)),
+    )
+    delete = sql_resolver.void(request=t.id_schema(), execute=delete_rows)
+    return Resolvers(
+        insert=insert.with_span(f"{prefix}.insertResolver"),
+        insert_void=insert_void.with_span(f"{prefix}.insertVoidResolver"),
+        find_by_id=find_by_id.with_span(f"{prefix}.findByIdResolver"),
+        delete=delete.with_span(f"{prefix}.deleteResolver"),
+    )
+
+
+__all__ = ["ModelType", "Repository", "Resolvers", "make_repository", "make_resolvers"]

pyfect/sql/mssql/__init__.py

@@ -0,0 +1,79 @@
+"""SQL Server on pytds (Effect's ``@effect/sql-mssql``; the
+``pyfect-dev[mssql]`` extra, never imported by ``pyfect``).
+
+pytds speaks TDS in pure Python, as tedious does in Node; each connection's
+calls run on a thread of its own, so the client works under ``run_blocking``
+and ``run_async`` and no fiber blocks::
+
+    from pyfect.sql import mssql
+
+    layer = mssql.layer(
+        mssql.MssqlClientConfig(
+            server="localhost", username="sa", password=redacted.make("..."), trust_server=True
+        )
+    )
+
+- ``client``: ``MssqlClient`` (an ``SqlClient`` with its ``config``,
+  ``param`` and ``call``), ``make``, ``layer``, ``layer_config``,
+  ``layer_from``, ``make_compiler``
+- ``config``: ``MssqlClientConfig``
+- ``types``: ``TYPES``, ``ParameterOptions``, ``default_parameter_types``
+- ``parameter`` / ``procedure``: stored procedure calls
+- ``error``: error number classification
+- ``migrator``: migrations
+
+Statements run through ``sp_executesql`` with ``@1``, ``@2``, ...
+parameters, typed by ``parameter_types`` unless given with ``param``.
+Values are pytds's: ``DECIMAL`` reads as ``Decimal``, ``DATETIME`` as a
+naive ``datetime`` (sent as its UTC wall clock when aware),
+``UNIQUEIDENTIFIER`` as ``uuid.UUID``, binary as ``bytes``. A request's
+rows are those of all its result sets in turn.
+"""
+
+from pyfect._extras import missing_extra
+
+try:
+    import OpenSSL  # noqa: F401  # pyright: ignore[reportUnusedImport]
+    import pytds  # noqa: F401  # pyright: ignore[reportUnusedImport, reportMissingTypeStubs]
+except ImportError as error:  # pragma: no cover - depends on the environment
+    raise missing_extra("pyfect.sql.mssql", "mssql") from error
+
+from pyfect.sql.mssql import client, config, error, migrator, parameter, procedure, types
+from pyfect.sql.mssql.client import (
+    MssqlClient,
+    MssqlClientService,
+    layer,
+    layer_config,
+    layer_from,
+    make,
+    make_compiler,
+)
+from pyfect.sql.mssql.config import MssqlClientConfig
+from pyfect.sql.mssql.parameter import Parameter
+from pyfect.sql.mssql.procedure import Procedure, Result
+from pyfect.sql.mssql.types import TYPES, DataType, ParameterOptions, default_parameter_types
+
+__all__ = [
+    "TYPES",
+    "DataType",
+    "MssqlClient",
+    "MssqlClientConfig",
+    "MssqlClientService",
+    "Parameter",
+    "ParameterOptions",
+    "Procedure",
+    "Result",
+    "client",
+    "config",
+    "default_parameter_types",
+    "error",
+    "layer",
+    "layer_config",
+    "layer_from",
+    "make",
+    "make_compiler",
+    "migrator",
+    "parameter",
+    "procedure",
+    "types",
+]

pyfect/sql/mssql/_connection.py

@@ -0,0 +1,169 @@
+"""The ``Connection`` of a SQL Server connection (the connection of Effect's
+``MssqlClient``): its blocking calls run on its worker thread, so no fiber
+blocks, and interrupting one cancels its request.
+
+Rows are those of every result set of the request in turn (tedious's
+``rowCollectionOnRequestCompletion``); ``execute_raw`` gives them as
+``execute`` does. Streams are not implemented, as in Effect.
+"""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from typing import TYPE_CHECKING, Any, cast
+
+from pyfect._core import Effect
+from pyfect.process._os import Latch
+from pyfect.sql.connection import Row, TransformRows, ValueRow
+from pyfect.sql.error import SqlError
+from pyfect.sql.mssql._driver import RawConnection, Rows, TypedValue
+from pyfect.sql.mssql._names import escape
+from pyfect.sql.mssql._worker import Worker
+from pyfect.sql.mssql.error import catch
+from pyfect.sql.mssql.procedure import Outputs, ProcedureWithValues, Result
+from pyfect.sql.mssql.types import DataType, ParameterOptions, ParameterTypes
+from pyfect.sql.statement import Custom, custom, is_custom, primitive_kind
+
+if TYPE_CHECKING:
+    from pyfect.stream import Stream
+
+type MssqlParam = Custom[str, DataType, object, ParameterOptions]
+
+mssql_param: Callable[[DataType, object, ParameterOptions], MssqlParam] = custom("MssqlParam")
+is_mssql_param = is_custom("MssqlParam")
+
+_EXECUTE = catch("Failed to execute statement", "execute")
+_BEGIN = catch("Failed to begin transaction", "beginTransaction")
+_COMMIT = catch("Failed to commit transaction", "commitTransaction")
+_SAVEPOINT = catch("Failed to create savepoint", "createSavepoint")
+_ROLLBACK = catch("Failed to rollback transaction", "rollbackTransaction")
+
+
+def _objects(rows: Rows) -> list[Row]:
+    return [dict(row) for row in rows]
+
+
+def _values(rows: Rows) -> list[ValueRow]:
+    return [tuple(value for _, value in row) for row in rows]
+
+
+class MssqlConnection:
+    """A ``Connection`` on one SQL Server connection."""
+
+    __slots__ = ("_ended", "_parameter_types", "_raw", "_worker")
+
+    def __init__(
+        self,
+        raw: RawConnection,
+        worker: Worker,
+        ended: Latch[None],
+        parameter_types: ParameterTypes,
+    ) -> None:
+        self._raw = raw
+        self._worker = worker
+        self._ended = ended
+        self._parameter_types = parameter_types
+
+    @property
+    def ended(self) -> bool:
+        """Whether the driver ended the connection."""
+        return self._ended.get() is not None
+
+    def _call[A](
+        self, run: Callable[[], A], on_error: Callable[[Exception], SqlError]
+    ) -> Effect[A, SqlError]:
+        return self._worker.call(run, on_error, self._raw)
+
+    def _typed(self, params: Sequence[object]) -> list[TypedValue]:
+        typed: list[TypedValue] = []
+        for i, value in enumerate(params):
+            name = str(i + 1)
+            if is_mssql_param(value):
+                param = cast("MssqlParam", value)
+                typed.append(TypedValue(name, param.param_a, param.param_b, param.param_c))
+            else:
+                kind = primitive_kind(value)
+                typed.append(
+                    TypedValue(name, self._parameter_types[kind], value, ParameterOptions())
+                )
+        return typed
+
+    def _run(self, sql: str, params: Sequence[object]) -> Effect[Rows, SqlError]:
+        raw = self._raw
+        typed = self._typed(params)
+        return self._call(lambda: raw.execute(sql, typed), _EXECUTE)
+
+    def execute(
+        self, sql: str, params: Sequence[object], transform_rows: TransformRows | None, /
+    ) -> Effect[Sequence[Row], SqlError]:
+        rows = self._run(sql, params).map(_objects)
+        if transform_rows is None:
+            return rows
+        transform = transform_rows
+        return rows.map(lambda found: list(transform(found)))
+
+    def execute_raw(self, sql: str, params: Sequence[object], /) -> Effect[object, SqlError]:
+        return self._run(sql, params).map(_objects)
+
+    def execute_values(
+        self, sql: str, params: Sequence[object], /
+    ) -> Effect[Sequence[ValueRow], SqlError]:
+        return self._run(sql, params).map(_values)
+
+    def execute_values_unprepared(
+        self, sql: str, params: Sequence[object], /
+    ) -> Effect[Sequence[ValueRow], SqlError]:
+        return self._run(sql, params).map(_values)
+
+    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_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 call[A](
+        self, procedure: ProcedureWithValues[A], transform_rows: TransformRows | None
+    ) -> Effect[Result[A], SqlError]:
+        """Run a stored procedure: its output parameters and rows."""
+        raw = self._raw
+        definition = procedure.procedure
+        params = [
+            TypedValue(p.name, p.type, procedure.values[p.name], p.options)
+            for p in definition.params
+        ]
+        outputs = [TypedValue(p.name, p.type, None, p.options) for p in definition.output_params]
+        name = escape(definition.name)
+
+        def result(found: tuple[Rows, dict[str, object]]) -> Result[A]:
+            rows: Sequence[Any] = _objects(found[0])
+            if transform_rows is not None:
+                rows = transform_rows(rows)
+            return Result(Outputs(found[1]), rows)
+
+        return self._call(lambda: raw.call_procedure(name, params, outputs), _EXECUTE).map(result)
+
+    @property
+    def begin(self) -> Effect[None, SqlError]:
+        return self._call(self._raw.begin, _BEGIN)
+
+    @property
+    def commit(self) -> Effect[None, SqlError]:
+        return self._call(self._raw.commit, _COMMIT)
+
+    def savepoint(self, name: str) -> Effect[None, SqlError]:
+        raw = self._raw
+        return self._call(lambda: raw.save(name), _SAVEPOINT)
+
+    def rollback(self, name: str | None = None) -> Effect[None, SqlError]:
+        raw = self._raw
+        return self._call(lambda: raw.rollback(name), _ROLLBACK)
+
+
+__all__ = ["MssqlConnection", "MssqlParam", "is_mssql_param", "mssql_param"]

pyfect/sql/mssql/_driver.py

@@ -0,0 +1,103 @@
+"""What the client needs of a SQL Server driver: a blocking connection,
+used from its own worker thread (``_worker``), that pytds provides
+(``_tds``) and tests replace.
+
+A connection runs one request at a time. ``cancel`` and ``close`` may be
+called from any thread: ``cancel`` stops the request in flight, which then
+raises; ``close`` ends the connection. A driver calls ``on_end`` (from any
+thread, maybe more than once) once its connection can no longer be used,
+as tedious emits ``end`` and ``error``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from typing import Protocol
+
+from pyfect.duration import Seconds
+from pyfect.sql.mssql.types import DataType, ParameterOptions
+
+type Column = tuple[str, object]
+"""A column of a row: its name and value."""
+
+type Rows = list[list[Column]]
+"""The rows of a request, those of every result set in turn (tedious's
+``rowCollectionOnRequestCompletion``)."""
+
+
+@dataclass(frozen=True, slots=True)
+class TypedValue:
+    """A parameter of a request: its name (without ``@``), type and value."""
+
+    name: str
+    type: DataType
+    value: object
+    options: ParameterOptions
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ConnectOptions:
+    """Where and how to connect, resolved from the client's config."""
+
+    server: str
+    port: int | None
+    instance_name: str | None
+    database: str | None
+    username: str | None
+    password: str | None
+    encrypt: bool
+    trust_server: bool
+    connect_timeout: Seconds
+    cancel_timeout: Seconds
+    connection_retry_interval: Seconds
+    max_retries_on_transient_errors: int
+
+
+class RawConnection(Protocol):
+    """A logged-in connection."""
+
+    def execute(self, sql: str, params: Sequence[TypedValue], /) -> Rows:
+        """Run ``sql`` (``sp_executesql``) with its ``@1``, ``@2``, ...
+        parameters; the first error the server reports is raised once the
+        request ends."""
+        ...
+
+    def call_procedure(
+        self, name: str, params: Sequence[TypedValue], outputs: Sequence[TypedValue], /
+    ) -> tuple[Rows, dict[str, object]]:
+        """Run the procedure ``name``: its rows and output values by name."""
+        ...
+
+    def begin(self) -> None: ...
+
+    def commit(self) -> None: ...
+
+    def save(self, name: str, /) -> None:
+        """Set the savepoint ``name``."""
+        ...
+
+    def rollback(self, name: str | None, /) -> None:
+        """Roll back the transaction, or to the savepoint ``name``."""
+        ...
+
+    def cancel(self) -> None:
+        """Stop the request in flight, or the next one if none is (any
+        thread; the client calls it only while a call runs)."""
+        ...
+
+    def forget_cancel(self) -> None:
+        """Drop a cancel not yet acted on (the client calls it as each call
+        ends, so a late cancel never stops the next call's request)."""
+        ...
+
+    def close(self) -> None:
+        """End the connection (any thread)."""
+        ...
+
+
+type Connect = Callable[[ConnectOptions, Callable[[], None]], RawConnection]
+"""Opens a connection (blocking); the callback is its ``on_end``."""
+
+
+__all__ = ["Column", "Connect", "ConnectOptions", "RawConnection", "Rows", "TypedValue"]

pyfect/sql/mssql/_names.py

@@ -0,0 +1,9 @@
+"""SQL Server names: ``[quoted]``, ``]`` doubled, each dot a boundary
+between quoted parts (``a.b`` is ``[a].[b]``)."""
+
+
+def escape(name: str) -> str:
+    return "[" + name.replace("]", "]]").replace(".", "].[") + "]"
+
+
+__all__ = ["escape"]