pyoq-sql 1.0.2__py3-none-any.whl

pyoq/query/mysql/aio/driver.py

@@ -0,0 +1,196 @@
+"""The typed boundary PyOQ holds the asynchronous MySQL driver to.
+
+The driver ships only generated type stubs that leave most of its surface
+unknown, so the shape PyOQ depends on is declared here and every reference to
+the driver is confined to this module. Everything above works against these
+protocols.
+"""
+
+from __future__ import annotations
+
+import ssl
+from collections.abc import Sequence
+from types import ModuleType
+from typing import Protocol, cast
+
+from pyoq.errors import ConnectionPoolError, OperationUnavailableError
+from pyoq.query.mysql.parameters import MySQLParameter
+from pyoq.schema.mysql.dsn import MySQLConnectionSettings
+
+_CHARSET = "utf8mb4"
+_FOUND_ROWS = 2
+_MISSING_DRIVER = (
+    "asynchronous MySQL support requires the asyncmy driver; "
+    "install pyoq-sql[mysql-async]"
+)
+
+
+class AsyncMySQLCursor(Protocol):
+    @property
+    def rowcount(self) -> int: ...
+
+    @property
+    def lastrowid(self) -> int: ...
+
+    async def execute(
+        self,
+        query: str,
+        args: tuple[MySQLParameter, ...],
+        /,
+    ) -> int: ...
+
+    async def fetchone(self) -> tuple[object, ...] | None: ...
+
+    async def fetchall(self) -> Sequence[object]: ...
+
+    async def fetchmany(self, size: int, /) -> Sequence[object]: ...
+
+    async def nextset(self) -> bool | None: ...
+
+    @property
+    def description(self) -> Sequence[object] | None: ...
+
+    async def close(self) -> None: ...
+
+
+class AsyncMySQLConnection(Protocol):
+    @property
+    def closed(self) -> bool: ...
+
+    async def cursor(self, cursor_class: object = ..., /) -> AsyncMySQLCursor: ...
+
+    def close(self) -> None: ...
+
+    async def ensure_closed(self) -> None: ...
+
+
+class _DriverConnection(Protocol):
+    """Only what the driver itself is asked for."""
+
+    async def cursor(self, cursor_class: object = ..., /) -> AsyncMySQLCursor: ...
+
+    def close(self) -> None: ...
+
+    async def ensure_closed(self) -> None: ...
+
+
+class OwnedConnection:
+    """A driver connection that knows whether it has been closed.
+
+    The driver keeps reporting a closed connection as connected, and reading
+    through one fails inside the driver with an attribute error rather than a
+    driver error that could be classified. Closure is therefore tracked here,
+    where it is the one fact the layers above rely on.
+    """
+
+    __slots__ = ("_closed", "_connection")
+
+    def __init__(self, connection: _DriverConnection) -> None:
+        self._connection = connection
+        self._closed = False
+
+    @property
+    def closed(self) -> bool:
+        return self._closed
+
+    async def cursor(self, cursor_class: object = None, /) -> AsyncMySQLCursor:
+        if cursor_class is None:
+            return await self._connection.cursor()
+        return await self._connection.cursor(cursor_class)
+
+    def close(self) -> None:
+        if self._closed:
+            return
+        self._closed = True
+        self._connection.close()
+
+    async def ensure_closed(self) -> None:
+        if self._closed:
+            return
+        self._closed = True
+        await self._connection.ensure_closed()
+
+
+def preferred_tls_context() -> ssl.SSLContext:
+    """Encrypt the connection without demanding a verifiable certificate.
+
+    This is the mode MySQL clients and the synchronous driver already use. A
+    MySQL server generates its own certificate, which no public authority
+    signs, so requiring verification would refuse the ordinary case. Encrypting
+    also keeps the password off the wire in clear text and avoids the RSA
+    exchange that would otherwise need a separate cryptography library.
+    """
+    context = ssl.create_default_context()
+    context.verify_flags &= ~ssl.VERIFY_X509_STRICT
+    context.check_hostname = False
+    context.verify_mode = ssl.CERT_NONE
+    return context
+
+
+def load_driver() -> ModuleType:
+    try:
+        import asyncmy
+    except ImportError as error:
+        raise OperationUnavailableError(_MISSING_DRIVER) from error
+    return asyncmy
+
+
+def driver_errors() -> type[BaseException]:
+    """The exception hierarchy this driver raises.
+
+    The codes match every other MySQL driver, but the classes do not, so the
+    layers above catch what this returns rather than naming a driver.
+    """
+    return cast("type[BaseException]", load_driver().errors.Error)
+
+
+def operational_errors() -> type[BaseException]:
+    """What the driver raises for a server-reported operational failure."""
+    return cast("type[BaseException]", load_driver().errors.OperationalError)
+
+
+def interface_errors() -> type[BaseException]:
+    """What the driver raises when its own connection is unusable."""
+    return cast("type[BaseException]", load_driver().errors.InterfaceError)
+
+
+def unbuffered_cursor_class() -> object:
+    """The driver's unbuffered cursor, which keeps streaming memory bounded."""
+    return cast("object", load_driver().cursors.SSCursor)
+
+
+async def open_connection(
+    settings: MySQLConnectionSettings,
+) -> AsyncMySQLConnection:
+    """Open one driver connection and hand it back as a typed protocol."""
+    driver = load_driver()
+    try:
+        connection = await driver.connect(
+            host=settings.host,
+            port=settings.port,
+            user=settings.user,
+            password=settings.password,
+            database=settings.database,
+            charset=_CHARSET,
+            autocommit=True,
+            client_flag=_FOUND_ROWS,
+            ssl=preferred_tls_context(),
+        )
+    except Exception as error:
+        message = f"unable to open MySQL connection: {error}"
+        raise ConnectionPoolError(message) from error
+    return OwnedConnection(cast("_DriverConnection", connection))
+
+
+__all__ = (
+    "AsyncMySQLConnection",
+    "AsyncMySQLCursor",
+    "OwnedConnection",
+    "driver_errors",
+    "interface_errors",
+    "load_driver",
+    "open_connection",
+    "operational_errors",
+    "preferred_tls_context",
+    "unbuffered_cursor_class",
+)

pyoq/query/mysql/aio/executor.py

@@ -0,0 +1,123 @@
+"""Asynchronous typed MySQL query execution."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from typing import TypeVar
+
+from pyoq.query.execution import (
+    CompiledQuery,
+    ExecutionControl,
+    StatementKind,
+    StreamPolicy,
+)
+from pyoq.query.execution.aio import AsyncRowStream, AsyncStreamResource
+from pyoq.query.execution.aio.pooling import AsyncConnectionLease
+from pyoq.query.mysql.aio.commands import (
+    AsyncExecutionEnvironment,
+    AsyncFailureHandler,
+    open_cursor,
+    run_sql,
+)
+from pyoq.query.mysql.aio.driver import AsyncMySQLConnection, AsyncMySQLCursor
+from pyoq.query.mysql.aio.operations import MySQLAsyncQueryOperations
+from pyoq.query.mysql.aio.pool import MySQLAsyncPool
+from pyoq.query.mysql.aio.transactions import MySQLAsyncTransaction
+from pyoq.query.mysql.compiler import MySQLCompiler
+from pyoq.query.mysql.parameters import adapt_parameters
+from pyoq.query.mysql.transactions import TransactionMode
+from pyoq.query.select import Query
+
+OperationResult = TypeVar("OperationResult")
+ResultRow = TypeVar("ResultRow")
+
+
+class MySQLAsyncExecutor(MySQLAsyncQueryOperations):
+    __slots__ = ("_pool",)
+
+    def __init__(
+        self,
+        pool: MySQLAsyncPool,
+        compiler: MySQLCompiler | None = None,
+    ) -> None:
+        self._pool = pool
+        super().__init__(compiler or MySQLCompiler())
+
+    @property
+    def pool(self) -> MySQLAsyncPool:
+        return self._pool
+
+    def stream(
+        self,
+        query: Query[ResultRow],
+        /,
+        *,
+        policy: StreamPolicy | None = None,
+    ) -> AsyncRowStream[ResultRow]:
+        selected = policy or StreamPolicy()
+        statement = self.compiler.compile(query)
+        return AsyncRowStream(lambda: self._open_stream(statement, selected), selected)
+
+    def transaction(
+        self,
+        mode: TransactionMode = TransactionMode.REPEATABLE_READ,
+        *,
+        control: ExecutionControl | None = None,
+    ) -> MySQLAsyncTransaction:
+        return MySQLAsyncTransaction(self.pool, self.compiler, mode, control)
+
+    def _environment(
+        self,
+        connection: AsyncMySQLConnection,
+        lease: AsyncConnectionLease[AsyncMySQLConnection],
+    ) -> AsyncExecutionEnvironment:
+        return AsyncExecutionEnvironment(
+            connection,
+            self.pool.connection_factory,
+            AsyncFailureHandler(lease.invalidate),
+        )
+
+    async def _run(
+        self,
+        statement: CompiledQuery,
+        operation: Callable[[AsyncMySQLCursor], Awaitable[OperationResult]],
+        control: ExecutionControl | None,
+    ) -> OperationResult:
+        parameters = adapt_parameters(statement.parameters)
+        lease = self.pool.checkout()
+        async with lease as connection:
+            return await run_sql(
+                self._environment(connection, lease),
+                statement.sql,
+                parameters,
+                operation,
+                control,
+                one_result_set=statement.statement_kind is StatementKind.CALL,
+            )
+
+    async def _open_stream(
+        self,
+        statement: CompiledQuery,
+        policy: StreamPolicy,
+    ) -> AsyncStreamResource:
+        parameters = adapt_parameters(statement.parameters)
+        lease = self.pool.checkout()
+        connection = await lease.__aenter__()
+        try:
+            session = await open_cursor(
+                self._environment(connection, lease),
+                statement.sql,
+                parameters,
+                policy.control,
+                unbuffered=True,
+            )
+        except BaseException:
+            await lease.__aexit__(None, None, None)
+            raise
+        return AsyncStreamResource(
+            session,
+            lambda: lease.__aexit__(None, None, None),
+        )
+
+
+__all__ = ("MySQLAsyncExecutor",)

pyoq/query/mysql/aio/factory.py

@@ -0,0 +1,26 @@
+"""Asynchronous MySQL connection creation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from pyoq.query.mysql.aio.driver import AsyncMySQLConnection, open_connection
+from pyoq.schema.mysql.dsn import parse_data_source_name
+
+
+@dataclass(frozen=True, slots=True)
+class MySQLAsyncConnectionFactory:
+    """Opens encrypted MySQL connections that count matched rows.
+
+    The transport is encrypted for the same reason the synchronous driver
+    encrypts it, and matched-row counting keeps an affected row count meaning
+    what it means on every other dialect.
+    """
+
+    dsn: str
+
+    async def __call__(self) -> AsyncMySQLConnection:
+        return await open_connection(parse_data_source_name(self.dsn))
+
+
+__all__ = ("MySQLAsyncConnectionFactory",)

pyoq/query/mysql/aio/operations.py

@@ -0,0 +1,38 @@
+"""Asynchronous MySQL typed result operations."""
+
+from __future__ import annotations
+
+from typing import cast
+
+from pyoq.query.execution import BulkPlan, WriteProvider
+from pyoq.query.execution.aio import AsyncDatabaseCursor, AsyncQueryOperations
+from pyoq.query.mysql.aio.driver import AsyncMySQLCursor
+from pyoq.query.mysql.compiler import MySQLCompiler
+from pyoq.query.mysql.planning import MySQLBulkPlanner
+from pyoq.query.write_nodes import WriteNode
+
+
+class MySQLAsyncQueryOperations(AsyncQueryOperations):
+    __slots__ = ("_compiler",)
+
+    def __init__(self, compiler: MySQLCompiler) -> None:
+        self._compiler = compiler
+
+    @property
+    def compiler(self) -> MySQLCompiler:
+        return self._compiler
+
+    def plan_bulk(self, statement: WriteProvider | WriteNode, /) -> BulkPlan:
+        return MySQLBulkPlanner(self.compiler).plan(statement)
+
+    def last_inserted_id(self, cursor: AsyncDatabaseCursor) -> int | None:
+        """Report the first identifier a multi-row insert generated.
+
+        MySQL reports the identifier of the first row an insert generated, not
+        the last, and reports zero when a statement generated none.
+        """
+        identifier = cast("AsyncMySQLCursor", cursor).lastrowid
+        return identifier if identifier > 0 else None
+
+
+__all__ = ("MySQLAsyncQueryOperations",)

pyoq/query/mysql/aio/pool.py

@@ -0,0 +1,53 @@
+"""Exclusive asynchronous MySQL connection pool."""
+
+from __future__ import annotations
+
+from typing import TypeAlias, cast
+
+from pyoq.errors import ConnectionPoolError
+from pyoq.query.execution.aio.pooling import AsyncConnectionLease, AsyncConnectionPool
+from pyoq.query.mysql.aio.commands import AsyncConnectionOpener
+from pyoq.query.mysql.aio.driver import (
+    AsyncMySQLConnection,
+    OwnedConnection,
+    driver_errors,
+)
+
+MySQLAsyncConnectionLease: TypeAlias = AsyncConnectionLease[AsyncMySQLConnection]
+
+_RESET_TIMEOUT = "SET @@max_execution_time = 0"
+_ROLLBACK = "ROLLBACK"
+
+
+class MySQLAsyncPool(AsyncConnectionPool[AsyncMySQLConnection]):
+    __slots__ = ()
+
+    @property
+    def connection_factory(self) -> AsyncConnectionOpener:
+        return self._factory
+
+    async def reset(self, connection: AsyncMySQLConnection) -> bool:
+        if connection.closed:
+            return False
+        try:
+            cursor = await connection.cursor()
+            await cursor.execute(_ROLLBACK, ())
+            await cursor.execute(_RESET_TIMEOUT, ())
+            await cursor.close()
+        except driver_errors():
+            return False
+        return not connection.closed
+
+    def validate(self, value: object) -> AsyncMySQLConnection:
+        if not isinstance(value, OwnedConnection):
+            message = "MySQL connection factory returned an invalid connection"
+            raise ConnectionPoolError(message)
+        return cast("AsyncMySQLConnection", value)
+
+    async def dispose(self, connection: AsyncMySQLConnection) -> None:
+        """Close a connection the driver has not already closed itself."""
+        if not connection.closed:
+            await connection.ensure_closed()
+
+
+__all__ = ("MySQLAsyncConnectionLease", "MySQLAsyncPool")