pyoq-sql 1.0.2__py3-none-any.whl

pyoq/query/mysql/compiler.py

@@ -0,0 +1,134 @@
+"""MySQL query and statement compiler."""
+
+from __future__ import annotations
+
+from pyoq.errors import UnsupportedQueryError
+from pyoq.query.execution import CompiledQuery, StatementKind
+from pyoq.query.mysql.context import MySQLCompilationContext
+from pyoq.query.mysql.expressions import MySQLExpressionCompiler
+from pyoq.query.mysql.identifiers import QUOTING
+from pyoq.query.mysql.model import MySQLCapabilities
+from pyoq.query.mysql.writes import MySQLWriteCompilation
+from pyoq.query.rendering.identifiers import IdentifierQuoting
+from pyoq.query.rendering.queries import QueryRenderer
+from pyoq.query.select_nodes import (
+    JoinKind,
+    LockStrength,
+    NullOrder,
+    SelectNode,
+    SetNode,
+)
+from pyoq.query.statements import StatementNode, StatementProvider
+from pyoq.query.write_nodes import CallNode, DeleteNode, InsertNode, UpdateNode
+
+_STATEMENT_NODES = (
+    SelectNode,
+    SetNode,
+    InsertNode,
+    UpdateNode,
+    DeleteNode,
+    CallNode,
+)
+_UNBOUNDED_ROWS = 18446744073709551615
+
+
+class MySQLCompiler:
+    __slots__ = ("_capabilities",)
+
+    def __init__(self, capabilities: MySQLCapabilities | None = None) -> None:
+        self._capabilities = capabilities or MySQLCapabilities()
+
+    @property
+    def capabilities(self) -> MySQLCapabilities:
+        return self._capabilities
+
+    def compile(
+        self,
+        statement: StatementProvider | StatementNode,
+        /,
+    ) -> CompiledQuery:
+        node = statement if isinstance(statement, _STATEMENT_NODES) else statement.node
+        context = MySQLCompilationContext(self.capabilities)
+        if isinstance(node, CallNode):
+            sql = MySQLWriteCompilation(context).compile_call(node)
+            return context.result(sql, StatementKind.CALL, node)
+        if isinstance(node, (InsertNode, UpdateNode, DeleteNode)):
+            sql, statement_kind = MySQLWriteCompilation(context).compile(node)
+            return context.result(sql, statement_kind, node)
+        sql = _MySQLQueryCompilation(context).compile(node)
+        return context.result(sql, StatementKind.SELECT, node)
+
+
+class _MySQLQueryCompilation(QueryRenderer):
+    __slots__ = ("_context",)
+
+    def __init__(self, context: MySQLCompilationContext) -> None:
+        self._context = context
+        super().__init__(MySQLExpressionCompiler(context))
+
+    @property
+    def dialect(self) -> str:
+        return "MySQL"
+
+    @property
+    def quoting(self) -> IdentifierQuoting:
+        return QUOTING
+
+    def require_join_capability(self, kind: JoinKind) -> None:
+        if kind is JoinKind.RIGHT and not self._context.capabilities.right_join:
+            message = "MySQL RIGHT JOIN is disabled by compiler capabilities"
+            raise UnsupportedQueryError(message)
+        if kind is JoinKind.FULL and not self._context.capabilities.full_join:
+            message = "MySQL does not support FULL JOIN"
+            raise UnsupportedQueryError(message)
+
+    def lock_strength_sql(self, strength: LockStrength) -> str:
+        """MySQL holds a row or shares it, and has no lock weaker than either."""
+        if strength in {LockStrength.NO_KEY_UPDATE, LockStrength.KEY_SHARE}:
+            message = (
+                f"MySQL has no {strength.value.replace('-', ' ')} lock; "
+                f"lock for update or for share instead"
+            )
+            raise UnsupportedQueryError(message)
+        return super().lock_strength_sql(strength)
+
+    def null_ordered(
+        self,
+        expression: str,
+        direction: str,
+        nulls: NullOrder,
+    ) -> str:
+        """MySQL has no NULLS clause, so it is told where nulls go by order.
+
+        It sorts nulls first in either direction, so ordering on whether a
+        value is null at all, before ordering on the value, puts them where
+        they were asked to go.
+        """
+        nulls_first = "DESC" if nulls is NullOrder.FIRST else "ASC"
+        return f"{expression} IS NULL {nulls_first}, {expression} {direction}"
+
+    def require_recursive_common_tables(self) -> None:
+        if not self._context.capabilities.recursive_common_tables:
+            message = "MySQL recursive common tables are disabled"
+            raise UnsupportedQueryError(message)
+
+    def require_lateral_sources(self) -> None:
+        if not self._context.capabilities.lateral_sources:
+            message = "MySQL has no lateral sources"
+            raise UnsupportedQueryError(message)
+
+    def append_pagination(
+        self,
+        fragments: list[str],
+        limit: int | None,
+        offset: int | None,
+    ) -> None:
+        if limit is not None:
+            fragments.append(f"LIMIT {self._context.bind_page_value(limit)}")
+        elif offset is not None:
+            fragments.append(f"LIMIT {_UNBOUNDED_ROWS}")
+        if offset is not None:
+            fragments.append(f"OFFSET {self._context.bind_page_value(offset)}")
+
+
+__all__ = ("MySQLCompiler",)

pyoq/query/mysql/context.py

@@ -0,0 +1,20 @@
+"""MySQL compilation context."""
+
+from __future__ import annotations
+
+from pyoq.query.execution import CompilationContext
+from pyoq.query.mysql.model import MySQLCapabilities
+
+
+class MySQLCompilationContext(CompilationContext):
+    __slots__ = ("capabilities",)
+
+    def __init__(self, capabilities: MySQLCapabilities) -> None:
+        super().__init__(
+            capabilities.maximum_parameters,
+            capabilities.parameter_style,
+        )
+        self.capabilities = capabilities
+
+
+__all__ = ("MySQLCompilationContext",)

pyoq/query/mysql/executor.py

@@ -0,0 +1,126 @@
+"""Synchronous typed MySQL query execution."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TypeVar
+
+from pymysql.cursors import Cursor
+
+from pyoq.query.execution import (
+    CompiledQuery,
+    ExecutionControl,
+    RowStream,
+    StatementKind,
+    StreamPolicy,
+    StreamResource,
+)
+from pyoq.query.execution.pooling import ConnectionLease
+from pyoq.query.mysql.commands import (
+    Connection,
+    ExecutionEnvironment,
+    FailureHandler,
+    open_cursor,
+    run_sql,
+)
+from pyoq.query.mysql.compiler import MySQLCompiler
+from pyoq.query.mysql.operations import MySQLQueryOperations
+from pyoq.query.mysql.parameters import adapt_parameters
+from pyoq.query.mysql.pool import MySQLPool
+from pyoq.query.mysql.transactions import MySQLTransaction, TransactionMode
+from pyoq.query.select import Query
+
+OperationResult = TypeVar("OperationResult")
+ResultRow = TypeVar("ResultRow")
+
+
+class MySQLExecutor(MySQLQueryOperations):
+    __slots__ = ("_pool",)
+
+    def __init__(
+        self,
+        pool: MySQLPool,
+        compiler: MySQLCompiler | None = None,
+    ) -> None:
+        self._pool = pool
+        super().__init__(compiler or MySQLCompiler())
+
+    @property
+    def pool(self) -> MySQLPool:
+        return self._pool
+
+    def stream(
+        self,
+        query: Query[ResultRow],
+        /,
+        *,
+        policy: StreamPolicy | None = None,
+    ) -> RowStream[ResultRow]:
+        selected = policy or StreamPolicy()
+        statement = self.compiler.compile(query)
+        return RowStream(
+            lambda: self._open_stream(statement, selected),
+            selected,
+            statement.row_types,
+        )
+
+    def transaction(
+        self,
+        mode: TransactionMode = TransactionMode.REPEATABLE_READ,
+        *,
+        control: ExecutionControl | None = None,
+    ) -> MySQLTransaction:
+        return MySQLTransaction(self.pool, self.compiler, mode, control)
+
+    def _environment(
+        self,
+        connection: Connection,
+        lease: ConnectionLease[Connection],
+    ) -> ExecutionEnvironment:
+        return ExecutionEnvironment(
+            connection,
+            self.pool.connection_factory,
+            FailureHandler(lease.invalidate),
+        )
+
+    def _run(
+        self,
+        statement: CompiledQuery,
+        operation: Callable[[Cursor], OperationResult],
+        control: ExecutionControl | None,
+    ) -> OperationResult:
+        parameters = adapt_parameters(statement.parameters)
+        lease = self.pool.checkout()
+        with lease as connection:
+            return run_sql(
+                self._environment(connection, lease),
+                statement.sql,
+                parameters,
+                operation,
+                control,
+                one_result_set=statement.statement_kind is StatementKind.CALL,
+            )
+
+    def _open_stream(
+        self,
+        statement: CompiledQuery,
+        policy: StreamPolicy,
+    ) -> StreamResource:
+        parameters = adapt_parameters(statement.parameters)
+        lease = self.pool.checkout()
+        connection = lease.__enter__()
+        try:
+            session = open_cursor(
+                self._environment(connection, lease),
+                statement.sql,
+                parameters,
+                policy.control,
+                unbuffered=True,
+            )
+        except BaseException:
+            lease.__exit__(None, None, None)
+            raise
+        return StreamResource(session, lambda: lease.__exit__(None, None, None))
+
+
+__all__ = ("MySQLExecutor",)

pyoq/query/mysql/expressions.py

@@ -0,0 +1,244 @@
+"""MySQL scalar expression compilation."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from pyoq.config import DatabaseDialect
+from pyoq.errors import UnsupportedQueryError
+from pyoq.query.mysql.context import MySQLCompilationContext
+from pyoq.query.mysql.identifiers import QUOTING
+from pyoq.query.nodes import (
+    BinaryNode,
+    BinaryOperator,
+    DatePart,
+    ExtractNode,
+    FieldNode,
+    FrameKind,
+    FrameNode,
+    FunctionName,
+    FunctionNode,
+    JsonContainsNode,
+    JsonKeysNode,
+    JsonNode,
+    JsonOperation,
+    JsonWrite,
+    JsonWriteNode,
+)
+from pyoq.query.rendering.expressions import (
+    CollectionFunctions,
+    ExpressionRenderer,
+)
+from pyoq.query.rendering.identifiers import IdentifierQuoting
+from pyoq.query.select_nodes import ELEMENT_COLUMN, JsonElementsSourceNode
+from pyoq.schema.models import TypeKind
+
+_EXCLUDED_ROW = "excluded"
+_ROW_ALIAS = "new"
+
+_DATE_FIELD = {
+    DatePart.YEAR: "YEAR",
+    DatePart.MONTH: "MONTH",
+    DatePart.DAY: "DAY",
+    DatePart.HOUR: "HOUR",
+    DatePart.MINUTE: "MINUTE",
+    DatePart.SECOND: "SECOND",
+}
+
+
+_MYSQL_CAST_SQL: Mapping[TypeKind, str] = {
+    TypeKind.SMALL_INTEGER: "SIGNED",
+    TypeKind.INTEGER: "SIGNED",
+    TypeKind.BIG_INTEGER: "SIGNED",
+    TypeKind.DECIMAL: "DECIMAL(65, 30)",
+    TypeKind.REAL: "FLOAT",
+    TypeKind.DOUBLE: "DOUBLE",
+    TypeKind.STRING: "CHAR",
+    TypeKind.BINARY: "BINARY",
+    TypeKind.DATE: "DATE",
+    TypeKind.TIME: "TIME",
+    TypeKind.DATETIME: "DATETIME",
+    TypeKind.JSON: "JSON",
+}
+"""MySQL casts to its own short list, and refuses the ANSI names outright.
+
+Verified against a running server: `INTEGER`, `TEXT`, `VARCHAR`, `NUMERIC`,
+`TIMESTAMP`, `INTERVAL`, and `UUID` are all syntax errors there, so the names
+here are the ones it accepts rather than the ones it stores.
+
+A bare `DECIMAL` means `DECIMAL(10, 0)` to MySQL, so casting `123.45` to one
+answers `123`. The largest precision it has is used instead, because a cast
+that quietly drops the fractional part of money is worse than no cast.
+"""
+
+
+_MYSQL_JSON_WRITES: Mapping[JsonWrite, str] = {
+    JsonWrite.SET: "JSON_SET",
+    JsonWrite.INSERT: "JSON_INSERT",
+    JsonWrite.REPLACE: "JSON_REPLACE",
+}
+
+
+class MySQLExpressionCompiler(ExpressionRenderer[MySQLCompilationContext]):
+    __slots__ = ()
+
+    @property
+    def collection_functions(self) -> CollectionFunctions:
+        # Measured: MySQL rejects ORDER BY inside JSON_ARRAYAGG.
+        return CollectionFunctions(
+            "JSON_ARRAYAGG",
+            "JSON_OBJECT",
+            "JSON_ARRAY()",
+            "JSON_ARRAY",
+            "JSON_OBJECTAGG",
+            ordered=False,
+        )
+
+    @property
+    def dialect(self) -> str:
+        return "MySQL"
+
+    def qualified_field(self, node: FieldNode) -> str:
+        table = _ROW_ALIAS if node.table == _EXCLUDED_ROW else node.table
+        schema = None if table == _ROW_ALIAS else node.schema
+        catalog = None if table == _ROW_ALIAS else node.catalog
+        return QUOTING.qualified(
+            node.name,
+            table=table,
+            schema=schema,
+            catalog=catalog,
+        )
+
+    def render_binary(self, node: BinaryNode, left: str, right: str) -> str:
+        if node.operator is BinaryOperator.CONCAT:
+            return f"CONCAT({left}, {right})"
+        if node.operator is BinaryOperator.IS_NOT_DISTINCT_FROM:
+            return f"({left} <=> {right})"
+        if node.operator is BinaryOperator.IS_DISTINCT_FROM:
+            return f"(NOT ({left} <=> {right}))"
+        return super().render_binary(node, left, right)
+
+    def validate_binary(self, node: BinaryNode) -> None:
+        del node
+
+    @property
+    def cast_type_names(self) -> Mapping[TypeKind, str]:
+        return _MYSQL_CAST_SQL
+
+    def render_json_elements(self, node: JsonElementsSourceNode) -> str:
+        """MySQL expands an array only through a table whose columns it states."""
+        subject = self.compile(node.expression)
+        alias = QUOTING.quote(node.alias)
+        return (
+            f"JSON_TABLE({subject}, '$[*]' "
+            f"COLUMNS ({ELEMENT_COLUMN} JSON PATH '$')) AS {alias}"
+        )
+
+    def render_json_keys(self, node: JsonKeysNode) -> str:
+        """MySQL names the members of an object itself."""
+        return f"JSON_KEYS({self.compile(node.expression)})"
+
+    def render_json(self, node: JsonNode) -> str:
+        """MySQL walks a written path, and refuses one written as a bare key."""
+        subject = self.compile(node.expression)
+        path = self.json_path_text(node.path)
+        if node.operation is JsonOperation.REMOVE:
+            return f"JSON_REMOVE({subject}, {path})"
+        if node.operation is JsonOperation.EXISTS:
+            return f"JSON_CONTAINS_PATH({subject}, 'one', {path})"
+        if node.operation is JsonOperation.LENGTH:
+            return f"JSON_LENGTH({subject}, {path})"
+        extracted = f"JSON_EXTRACT({subject}, {path})"
+        if node.operation is JsonOperation.TEXT:
+            return self._json_text(node, extracted)
+        return extracted
+
+    def _json_text(self, node: JsonNode, extracted: str) -> str:
+        """A JSON null read as text is no text, the way the others read it.
+
+        MySQL unquotes a JSON null into the four letters of its name, so a
+        member holding null and a member holding "null" answer alike and both
+        differ from what PostgreSQL and SQLite answer. The value is asked for
+        a second time because each asking binds the path again.
+        """
+        again = (
+            f"JSON_EXTRACT({self.compile(node.expression)}, "
+            f"{self.json_path_text(node.path)})"
+        )
+        return (
+            f"CASE WHEN JSON_TYPE({extracted}) = 'NULL' THEN NULL "
+            f"ELSE JSON_UNQUOTE({again}) END"
+        )
+
+    def render_json_write(self, node: JsonWriteNode) -> str:
+        """Compiled in the order it is written, because binding follows that.
+
+        A value compiled before the path it is written at would take the
+        earlier placeholder, and the two would swap.
+        """
+        subject = self.compile(node.expression)
+        if node.operation is JsonWrite.MERGE:
+            return f"JSON_MERGE_PATCH({subject}, {self.compile(node.value)})"
+        if node.operation is JsonWrite.CONCAT:
+            raise UnsupportedQueryError(_NO_CONCAT)
+        path = self.json_path_text(node.path)
+        value = self.compile(node.value)
+        return f"{_MYSQL_JSON_WRITES[node.operation]}({subject}, {path}, {value})"
+
+    def render_json_contains(self, node: JsonContainsNode) -> str:
+        subject = self.compile(node.expression)
+        return f"JSON_CONTAINS({subject}, {self.compile(node.value)})"
+
+    @property
+    def quoting(self) -> IdentifierQuoting:
+        return QUOTING
+
+    @property
+    def database_dialect(self) -> DatabaseDialect:
+        return DatabaseDialect.MYSQL
+
+    def require_frame(self, node: FrameNode) -> None:
+        """MySQL counts rows and values, and has no peer groups to count."""
+        if node.kind is FrameKind.GROUPS:
+            message = "MySQL has no GROUPS frame; count rows or values instead"
+            raise UnsupportedQueryError(message)
+        if node.exclusion is not None:
+            message = "MySQL cannot exclude rows from a frame"
+            raise UnsupportedQueryError(message)
+
+    def render_extract(self, node: ExtractNode) -> str:
+        field = _DATE_FIELD.get(node.part)
+        if field is None:
+            message = f"unsupported MySQL date part: {node.part}"
+            raise UnsupportedQueryError(message)
+        return f"CAST(EXTRACT({field} FROM {self.compile(node.expression)}) AS SIGNED)"
+
+    def render_string_predicate(self, node: FunctionNode) -> str:
+        left_node, right_node = node.arguments
+        left = self.compile(left_node)
+        right = self.compile(right_node)
+        if node.name is FunctionName.CONTAINS:
+            return f"(INSTR({left}, {right}) > 0)"
+        if node.name is FunctionName.STARTS_WITH:
+            comparison = self.compile(right_node)
+            return f"(LEFT({left}, CHAR_LENGTH({right})) = {comparison})"
+        if node.name is FunctionName.ENDS_WITH:
+            comparison = self.compile(right_node)
+            return f"(RIGHT({left}, CHAR_LENGTH({right})) = {comparison})"
+        message = f"unsupported MySQL function: {node.name}"
+        raise UnsupportedQueryError(message)
+
+    def require_raw_expressions(self) -> None:
+        if not self._context.capabilities.raw_expressions:
+            message = "MySQL raw expressions are disabled by compiler capabilities"
+            raise UnsupportedQueryError(message)
+
+
+__all__ = ("MySQLExpressionCompiler",)
+
+
+_NO_CONCAT = (
+    "MySQL merges a document all the way down and has no one-level "
+    "concatenation; json_merge says what it does"
+)
+"""Refused rather than emulated, because all the way down is not one level."""

pyoq/query/mysql/factory.py

@@ -0,0 +1,46 @@
+"""MySQL runtime connection creation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import pymysql
+from pymysql.constants import CLIENT
+
+from pyoq.errors import ConnectionPoolError
+from pyoq.query.mysql.commands import Connection
+from pyoq.schema.mysql.dsn import parse_data_source_name
+
+_CHARSET = "utf8mb4"
+
+
+@dataclass(frozen=True, slots=True)
+class MySQLConnectionFactory:
+    """Opens MySQL connections that count matched rows, not changed rows.
+
+    ``CLIENT.FOUND_ROWS`` makes an affected row count mean the same thing it
+    means for every other dialect, so an update that writes a column's existing
+    value still reports the row it matched.
+    """
+
+    dsn: str
+
+    def __call__(self) -> Connection:
+        settings = parse_data_source_name(self.dsn)
+        try:
+            return pymysql.connect(
+                host=settings.host,
+                port=settings.port,
+                user=settings.user,
+                password=settings.password,
+                database=settings.database,
+                charset=_CHARSET,
+                autocommit=True,
+                client_flag=CLIENT.FOUND_ROWS,
+            )
+        except pymysql.Error as error:
+            message = f"unable to open MySQL connection: {error}"
+            raise ConnectionPoolError(message) from error
+
+
+__all__ = ("MySQLConnectionFactory",)

pyoq/query/mysql/health.py

@@ -0,0 +1,66 @@
+"""MySQL failure classification, by server error code.
+
+Every MySQL driver reports the same numeric codes while raising exceptions from
+its own hierarchy, so classification lives here and each driver contributes only
+the exception types it raises.
+"""
+
+from __future__ import annotations
+
+_CANCELLED_CODE = 1317
+_TIMEOUT_CODE = 3024
+_CONNECTION_FAILURE_CODES = frozenset(
+    {
+        1053,  # server shutdown in progress
+        1152,  # aborted connection
+        1927,  # connection killed
+        2002,  # client cannot reach the server socket
+        2003,  # client cannot reach the server host
+        2006,  # server has gone away
+        2013,  # connection lost during a query
+        2055,  # connection lost with a system error
+    }
+)
+_TRANSACTION_ABORT_CODES = frozenset(
+    {
+        1213,  # deadlock; the server rolled the whole transaction back
+        1614,  # distributed transaction rolled back on deadlock
+    }
+)
+
+
+def error_code(error: BaseException) -> int | None:
+    arguments = error.args
+    if not arguments or not isinstance(arguments[0], int):
+        return None
+    return arguments[0]
+
+
+def is_cancellation(error: BaseException) -> bool:
+    return error_code(error) == _CANCELLED_CODE
+
+
+def is_timeout(error: BaseException) -> bool:
+    return error_code(error) == _TIMEOUT_CODE
+
+
+def is_connection_failure(error: BaseException) -> bool:
+    """Report whether the server said the connection itself is gone.
+
+    A driver also signals a locally closed connection through its own interface
+    error, which carries no server code, so each driver checks for that itself.
+    """
+    return error_code(error) in _CONNECTION_FAILURE_CODES
+
+
+def is_transaction_abort(error: BaseException) -> bool:
+    return error_code(error) in _TRANSACTION_ABORT_CODES
+
+
+__all__ = (
+    "error_code",
+    "is_cancellation",
+    "is_connection_failure",
+    "is_timeout",
+    "is_transaction_abort",
+)

pyoq/query/mysql/identifiers.py

@@ -0,0 +1,9 @@
+"""MySQL identifier rendering."""
+
+from __future__ import annotations
+
+from pyoq.query.rendering.identifiers import IdentifierQuoting
+
+QUOTING = IdentifierQuoting("MySQL", delimiter="`")
+
+__all__ = ("QUOTING",)