sqlspec 0.36.0__cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl

sqlspec/adapters/asyncmy/config.py

@@ -0,0 +1,302 @@
+"""Asyncmy database configuration."""
+
+from typing import TYPE_CHECKING, Any, ClassVar, TypedDict, cast
+
+import asyncmy
+from asyncmy.cursors import Cursor, DictCursor  # pyright: ignore
+from asyncmy.pool import Pool as AsyncmyPool  # pyright: ignore
+from mypy_extensions import mypyc_attr
+from typing_extensions import NotRequired
+
+from sqlspec.adapters.asyncmy._typing import AsyncmyConnection
+from sqlspec.adapters.asyncmy.core import apply_driver_features, default_statement_config
+from sqlspec.adapters.asyncmy.driver import AsyncmyCursor, AsyncmyDriver, AsyncmyExceptionHandler, AsyncmySessionContext
+from sqlspec.config import AsyncDatabaseConfig, ExtensionConfigs
+from sqlspec.extensions.events import EventRuntimeHints
+from sqlspec.utils.config_tools import normalize_connection_config, reject_pool_aliases
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from asyncmy.cursors import Cursor, DictCursor  # pyright: ignore
+    from asyncmy.pool import Pool  # pyright: ignore
+
+    from sqlspec.core import StatementConfig
+    from sqlspec.observability import ObservabilityConfig
+
+
+__all__ = ("AsyncmyConfig", "AsyncmyConnectionParams", "AsyncmyDriverFeatures", "AsyncmyPoolParams")
+
+
+class AsyncmyConnectionParams(TypedDict):
+    """Asyncmy connection parameters."""
+
+    host: NotRequired[str]
+    user: NotRequired[str]
+    password: NotRequired[str]
+    database: NotRequired[str]
+    port: NotRequired[int]
+    unix_socket: NotRequired[str]
+    charset: NotRequired[str]
+    connect_timeout: NotRequired[int]
+    read_default_file: NotRequired[str]
+    read_default_group: NotRequired[str]
+    autocommit: NotRequired[bool]
+    local_infile: NotRequired[bool]
+    ssl: NotRequired[Any]
+    sql_mode: NotRequired[str]
+    init_command: NotRequired[str]
+    cursor_class: NotRequired[type["Cursor"] | type["DictCursor"]]
+    extra: NotRequired["dict[str, Any]"]
+
+
+class AsyncmyPoolParams(AsyncmyConnectionParams):
+    """Asyncmy pool parameters."""
+
+    minsize: NotRequired[int]
+    maxsize: NotRequired[int]
+    echo: NotRequired[bool]
+    pool_recycle: NotRequired[int]
+
+
+class AsyncmyDriverFeatures(TypedDict):
+    """Asyncmy driver feature flags.
+
+    MySQL/MariaDB handle JSON natively, but custom serializers can be provided
+    for specialized use cases (e.g., orjson for performance, msgspec for type safety).
+
+    json_serializer: Custom JSON serializer function.
+        Defaults to sqlspec.utils.serializers.to_json.
+        Use for performance (orjson) or custom encoding.
+    json_deserializer: Custom JSON deserializer function.
+        Defaults to sqlspec.utils.serializers.from_json.
+        Use for performance (orjson) or custom decoding.
+    enable_events: Enable database event channel support.
+        Defaults to True when extension_config["events"] is configured.
+        Provides pub/sub capabilities via table-backed queue (MySQL/MariaDB have no native pub/sub).
+        Requires extension_config["events"] for migration setup.
+    events_backend: Event channel backend selection.
+        Only option: "table_queue" (durable table-backed queue with retries and exactly-once delivery).
+        MySQL/MariaDB do not have native pub/sub, so table_queue is the only backend.
+        Defaults to "table_queue".
+    """
+
+    json_serializer: NotRequired["Callable[[Any], str]"]
+    json_deserializer: NotRequired["Callable[[str], Any]"]
+    enable_events: NotRequired[bool]
+    events_backend: NotRequired[str]
+
+
+class _AsyncmySessionFactory:
+    __slots__ = ("_config", "_ctx")
+
+    def __init__(self, config: "AsyncmyConfig") -> None:
+        self._config = config
+        self._ctx: Any | None = None
+
+    async def acquire_connection(self) -> "AsyncmyConnection":
+        pool = self._config.connection_instance
+        if pool is None:
+            pool = await self._config.create_pool()
+            self._config.connection_instance = pool
+        ctx = pool.acquire()
+        self._ctx = ctx
+        return cast("AsyncmyConnection", await ctx.__aenter__())
+
+    async def release_connection(self, _conn: "AsyncmyConnection") -> None:
+        if self._ctx is not None:
+            await self._ctx.__aexit__(None, None, None)
+            self._ctx = None
+
+
+class AsyncmyConnectionContext:
+    """Async context manager for Asyncmy connections."""
+
+    __slots__ = ("_config", "_ctx")
+
+    def __init__(self, config: "AsyncmyConfig") -> None:
+        self._config = config
+        self._ctx: Any = None
+
+    async def __aenter__(self) -> AsyncmyConnection:
+        pool = self._config.connection_instance
+        if pool is None:
+            pool = await self._config.create_pool()
+            self._config.connection_instance = pool
+        ctx = pool.acquire()
+        self._ctx = ctx
+        return cast("AsyncmyConnection", await ctx.__aenter__())
+
+    async def __aexit__(
+        self, exc_type: "type[BaseException] | None", exc_val: "BaseException | None", exc_tb: Any
+    ) -> bool | None:
+        if self._ctx:
+            return cast("bool | None", await self._ctx.__aexit__(exc_type, exc_val, exc_tb))
+        return None
+
+
+@mypyc_attr(native_class=False)
+class AsyncmyConfig(AsyncDatabaseConfig[AsyncmyConnection, "AsyncmyPool", AsyncmyDriver]):  # pyright: ignore
+    """Configuration for Asyncmy database connections."""
+
+    driver_type: ClassVar[type[AsyncmyDriver]] = AsyncmyDriver
+    connection_type: "ClassVar[type[Any]]" = cast("type[Any]", AsyncmyConnection)
+    supports_transactional_ddl: ClassVar[bool] = False
+    supports_native_arrow_export: ClassVar[bool] = True
+    supports_native_parquet_export: ClassVar[bool] = True
+    supports_native_arrow_import: ClassVar[bool] = True
+    supports_native_parquet_import: ClassVar[bool] = True
+
+    def __init__(
+        self,
+        *,
+        connection_config: "AsyncmyPoolParams | dict[str, Any] | None" = None,
+        connection_instance: "AsyncmyPool | None" = None,
+        migration_config: "dict[str, Any] | None" = None,
+        statement_config: "StatementConfig | None" = None,
+        driver_features: "AsyncmyDriverFeatures | dict[str, Any] | None" = None,
+        bind_key: "str | None" = None,
+        extension_config: "ExtensionConfigs | None" = None,
+        observability_config: "ObservabilityConfig | None" = None,
+        **kwargs: Any,
+    ) -> None:
+        """Initialize Asyncmy configuration.
+
+        Args:
+            connection_config: Connection and pool configuration parameters
+            connection_instance: Existing pool instance to use
+            migration_config: Migration configuration
+            statement_config: Statement configuration override
+            driver_features: Driver feature configuration (TypedDict or dict)
+            bind_key: Optional unique identifier for this configuration
+            extension_config: Extension-specific configuration (e.g., Litestar plugin settings)
+            observability_config: Adapter-level observability overrides for lifecycle hooks and observers
+            **kwargs: Additional keyword arguments
+        """
+        reject_pool_aliases(kwargs)
+
+        connection_config = normalize_connection_config(connection_config)
+
+        connection_config.setdefault("host", "localhost")
+        connection_config.setdefault("port", 3306)
+
+        statement_config = statement_config or default_statement_config
+        statement_config, driver_features = apply_driver_features(statement_config, driver_features)
+
+        super().__init__(
+            connection_config=connection_config,
+            connection_instance=connection_instance,
+            migration_config=migration_config,
+            statement_config=statement_config,
+            driver_features=driver_features,
+            bind_key=bind_key,
+            extension_config=extension_config,
+            observability_config=observability_config,
+            **kwargs,
+        )
+
+    async def _create_pool(self) -> "AsyncmyPool":
+        """Create the actual async connection pool.
+
+        MySQL/MariaDB handle JSON types natively without requiring connection-level
+        type handlers. JSON serialization is handled via type_coercion_map in the
+        driver's statement_config (see driver.py).
+
+        Future driver_features can be added here if needed (e.g., custom connection
+        initialization, specialized type handling).
+        """
+        return cast("AsyncmyPool", await asyncmy.create_pool(**dict(self.connection_config)))
+
+    async def _close_pool(self) -> None:
+        """Close the actual async connection pool."""
+        if self.connection_instance:
+            self.connection_instance.close()
+            await self.connection_instance.wait_closed()
+            self.connection_instance = None
+
+    async def close_pool(self) -> None:
+        """Close the connection pool."""
+        await self._close_pool()
+
+    async def create_connection(self) -> AsyncmyConnection:
+        """Create a single async connection (not from pool).
+
+        Returns:
+            An Asyncmy connection instance.
+        """
+        pool = self.connection_instance
+        if pool is None:
+            pool = await self.create_pool()
+            self.connection_instance = pool
+        return cast("AsyncmyConnection", await pool.acquire())
+
+    def provide_connection(self, *args: Any, **kwargs: Any) -> "AsyncmyConnectionContext":
+        """Provide an async connection context manager.
+
+        Args:
+            *args: Additional arguments.
+            **kwargs: Additional keyword arguments.
+
+        Returns:
+            An Asyncmy connection context manager.
+        """
+        return AsyncmyConnectionContext(self)
+
+    def provide_session(
+        self, *_args: Any, statement_config: "StatementConfig | None" = None, **_kwargs: Any
+    ) -> "AsyncmySessionContext":
+        """Provide an async driver session context manager.
+
+        Args:
+            *_args: Additional arguments.
+            statement_config: Optional statement configuration override.
+            **_kwargs: Additional keyword arguments.
+
+        Returns:
+            An Asyncmy driver session context manager.
+        """
+        factory = _AsyncmySessionFactory(self)
+        return AsyncmySessionContext(
+            acquire_connection=factory.acquire_connection,
+            release_connection=factory.release_connection,
+            statement_config=statement_config or self.statement_config or default_statement_config,
+            driver_features=self.driver_features,
+            prepare_driver=self._prepare_driver,
+        )
+
+    async def provide_pool(self, *args: Any, **kwargs: Any) -> "Pool":
+        """Provide async pool instance.
+
+        Returns:
+            The async connection pool.
+        """
+        if not self.connection_instance:
+            self.connection_instance = await self.create_pool()
+        return self.connection_instance
+
+    def get_signature_namespace(self) -> "dict[str, Any]":
+        """Get the signature namespace for Asyncmy types.
+
+        Returns:
+            Dictionary mapping type names to types.
+        """
+
+        namespace = super().get_signature_namespace()
+        namespace.update({
+            "AsyncmyConnectionContext": AsyncmyConnectionContext,
+            "AsyncmyConnection": AsyncmyConnection,
+            "AsyncmyConnectionParams": AsyncmyConnectionParams,
+            "AsyncmyCursor": AsyncmyCursor,
+            "AsyncmyDriver": AsyncmyDriver,
+            "AsyncmyDriverFeatures": AsyncmyDriverFeatures,
+            "AsyncmyExceptionHandler": AsyncmyExceptionHandler,
+            "AsyncmyPool": AsyncmyPool,
+            "AsyncmyPoolParams": AsyncmyPoolParams,
+            "AsyncmySessionContext": AsyncmySessionContext,
+        })
+        return namespace
+
+    def get_event_runtime_hints(self) -> "EventRuntimeHints":
+        """Return queue polling defaults for Asyncmy adapters."""
+
+        return EventRuntimeHints(poll_interval=0.25, lease_seconds=5, select_for_update=True, skip_locked=True)

sqlspec/adapters/asyncmy/core.py

@@ -0,0 +1,360 @@
+"""AsyncMy adapter compiled helpers."""
+
+from typing import TYPE_CHECKING, Any
+
+from sqlspec.core import DriverParameterProfile, ParameterStyle, StatementConfig, build_statement_config_from_profile
+from sqlspec.exceptions import (
+    CheckViolationError,
+    DatabaseConnectionError,
+    DataError,
+    ForeignKeyViolationError,
+    IntegrityError,
+    NotNullViolationError,
+    SQLParsingError,
+    SQLSpecError,
+    TransactionError,
+    UniqueViolationError,
+)
+from sqlspec.utils.serializers import from_json, to_json
+from sqlspec.utils.type_guards import has_cursor_metadata, has_lastrowid, has_rowcount, has_sqlstate, has_type_code
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Mapping, Sequence
+
+__all__ = (
+    "apply_driver_features",
+    "build_insert_statement",
+    "build_profile",
+    "build_statement_config",
+    "collect_rows",
+    "create_mapped_exception",
+    "default_statement_config",
+    "detect_json_columns",
+    "driver_profile",
+    "format_identifier",
+    "normalize_execute_many_parameters",
+    "normalize_execute_parameters",
+    "normalize_lastrowid",
+    "resolve_rowcount",
+)
+
+MYSQL_ER_DUP_ENTRY = 1062
+MYSQL_ER_NO_DEFAULT_FOR_FIELD = 1364
+MYSQL_ER_CHECK_CONSTRAINT_VIOLATED = 3819
+
+
+def _bool_to_int(value: bool) -> int:
+    return int(value)
+
+
+def _quote_mysql_identifier(identifier: str) -> str:
+    normalized = identifier.replace("`", "``")
+    return f"`{normalized}`"
+
+
+def format_identifier(identifier: str) -> str:
+    cleaned = identifier.strip()
+    if not cleaned:
+        msg = "Table name must not be empty"
+        raise SQLSpecError(msg)
+    parts = [part for part in cleaned.split(".") if part]
+    formatted = ".".join(_quote_mysql_identifier(part) for part in parts)
+    return formatted or _quote_mysql_identifier(cleaned)
+
+
+def build_insert_statement(table: str, columns: "list[str]") -> str:
+    column_clause = ", ".join(_quote_mysql_identifier(column) for column in columns)
+    placeholders = ", ".join("%s" for _ in columns)
+    return f"INSERT INTO {format_identifier(table)} ({column_clause}) VALUES ({placeholders})"
+
+
+def normalize_execute_parameters(parameters: Any) -> Any:
+    """Normalize parameters for AsyncMy execute calls.
+
+    Args:
+        parameters: Prepared parameters payload.
+
+    Returns:
+        Normalized parameters payload.
+    """
+    return parameters or None
+
+
+def normalize_execute_many_parameters(parameters: Any) -> Any:
+    """Normalize parameters for AsyncMy executemany calls.
+
+    Args:
+        parameters: Prepared parameters payload.
+
+    Returns:
+        Normalized parameters payload.
+
+    Raises:
+        ValueError: When parameters are missing for executemany.
+    """
+    if not parameters:
+        msg = "execute_many requires parameters"
+        raise ValueError(msg)
+    return parameters
+
+
+def build_profile() -> "DriverParameterProfile":
+    """Create the AsyncMy driver parameter profile."""
+
+    return DriverParameterProfile(
+        name="AsyncMy",
+        default_style=ParameterStyle.QMARK,
+        supported_styles={ParameterStyle.QMARK, ParameterStyle.POSITIONAL_PYFORMAT},
+        default_execution_style=ParameterStyle.POSITIONAL_PYFORMAT,
+        supported_execution_styles={ParameterStyle.POSITIONAL_PYFORMAT},
+        has_native_list_expansion=False,
+        preserve_parameter_format=True,
+        needs_static_script_compilation=True,
+        allow_mixed_parameter_styles=False,
+        preserve_original_params_for_many=False,
+        json_serializer_strategy="helper",
+        custom_type_coercions={bool: _bool_to_int},
+        default_dialect="mysql",
+    )
+
+
+driver_profile = build_profile()
+
+
+def build_statement_config(
+    *, json_serializer: "Callable[[Any], str] | None" = None, json_deserializer: "Callable[[str], Any] | None" = None
+) -> "StatementConfig":
+    """Construct the AsyncMy statement configuration with optional JSON codecs."""
+    serializer = json_serializer or to_json
+    deserializer = json_deserializer or from_json
+    profile = driver_profile
+    return build_statement_config_from_profile(
+        profile, statement_overrides={"dialect": "mysql"}, json_serializer=serializer, json_deserializer=deserializer
+    )
+
+
+default_statement_config = build_statement_config()
+
+
+def apply_driver_features(
+    statement_config: "StatementConfig", driver_features: "Mapping[str, Any] | None"
+) -> "tuple[StatementConfig, dict[str, Any]]":
+    """Apply AsyncMy driver feature defaults to statement config."""
+    features: dict[str, Any] = dict(driver_features) if driver_features else {}
+    json_serializer = features.setdefault("json_serializer", to_json)
+    json_deserializer = features.setdefault("json_deserializer", from_json)
+
+    if json_serializer is not None:
+        parameter_config = statement_config.parameter_config.with_json_serializers(
+            json_serializer, deserializer=json_deserializer
+        )
+        statement_config = statement_config.replace(parameter_config=parameter_config)
+
+    return statement_config, features
+
+
+def _create_mysql_error(
+    error: Any, sqlstate: "str | None", code: "int | None", error_class: type[SQLSpecError], description: str
+) -> SQLSpecError:
+    """Create a MySQL error instance without raising it."""
+    code_str = f"[{sqlstate or code}]" if sqlstate or code else ""
+    msg = f"MySQL {description} {code_str}: {error}" if code_str else f"MySQL {description}: {error}"
+    exc = error_class(msg)
+    exc.__cause__ = error
+    return exc
+
+
+def create_mapped_exception(error: Any, *, logger: Any | None = None) -> "SQLSpecError | bool":
+    """Map AsyncMy exceptions to SQLSpec errors.
+
+    This is a factory function that returns an exception instance rather than
+    raising. This pattern is more robust for use in __exit__ handlers and
+    avoids issues with exception control flow in different Python versions.
+
+    Args:
+        error: The AsyncMy exception to map
+        logger: Optional logger for migration warnings
+
+    Returns:
+        True to suppress expected migration errors, or a SQLSpec exception
+    """
+    error_code = error.args[0] if len(error.args) >= 1 and isinstance(error.args[0], int) else None
+    sqlstate = error.sqlstate if has_sqlstate(error) and error.sqlstate is not None else None
+
+    if error_code in {1061, 1091}:
+        if logger is not None:
+            logger.warning("AsyncMy MySQL expected migration error (ignoring): %s", error)
+        return True
+
+    if sqlstate == "23505" or error_code == MYSQL_ER_DUP_ENTRY:
+        return _create_mysql_error(error, sqlstate, error_code, UniqueViolationError, "unique constraint violation")
+    if sqlstate == "23503" or error_code in {1216, 1217, 1451, 1452}:
+        return _create_mysql_error(
+            error, sqlstate, error_code, ForeignKeyViolationError, "foreign key constraint violation"
+        )
+    if sqlstate == "23502" or error_code in {1048, MYSQL_ER_NO_DEFAULT_FOR_FIELD}:
+        return _create_mysql_error(error, sqlstate, error_code, NotNullViolationError, "not-null constraint violation")
+    if sqlstate == "23514" or error_code == MYSQL_ER_CHECK_CONSTRAINT_VIOLATED:
+        return _create_mysql_error(error, sqlstate, error_code, CheckViolationError, "check constraint violation")
+    if sqlstate and sqlstate.startswith("23"):
+        return _create_mysql_error(error, sqlstate, error_code, IntegrityError, "integrity constraint violation")
+    if sqlstate and sqlstate.startswith("42"):
+        return _create_mysql_error(error, sqlstate, error_code, SQLParsingError, "SQL syntax error")
+    if sqlstate and sqlstate.startswith("08"):
+        return _create_mysql_error(error, sqlstate, error_code, DatabaseConnectionError, "connection error")
+    if sqlstate and sqlstate.startswith("40"):
+        return _create_mysql_error(error, sqlstate, error_code, TransactionError, "transaction error")
+    if sqlstate and sqlstate.startswith("22"):
+        return _create_mysql_error(error, sqlstate, error_code, DataError, "data error")
+    if error_code in {2002, 2003, 2005, 2006, 2013}:
+        return _create_mysql_error(error, sqlstate, error_code, DatabaseConnectionError, "connection error")
+    if error_code in {1205, 1213}:
+        return _create_mysql_error(error, sqlstate, error_code, TransactionError, "transaction error")
+    if error_code in range(1064, 1100):
+        return _create_mysql_error(error, sqlstate, error_code, SQLParsingError, "SQL syntax error")
+    return _create_mysql_error(error, sqlstate, error_code, SQLSpecError, "database error")
+
+
+def detect_json_columns(cursor: Any, json_type_codes: "set[int]") -> "list[int]":
+    """Identify JSON column indexes from cursor metadata.
+
+    Args:
+        cursor: Database cursor with description metadata available.
+        json_type_codes: Set of type codes identifying JSON columns.
+
+    Returns:
+        List of index positions where JSON values are present.
+    """
+    if not has_cursor_metadata(cursor):
+        return []
+    description = cursor.description
+    if not description or not json_type_codes:
+        return []
+
+    json_indexes: list[int] = []
+    for index, column in enumerate(description):
+        if has_type_code(column):
+            type_code = column.type_code
+        elif isinstance(column, (tuple, list)) and len(column) > 1:
+            type_code = column[1]
+        else:
+            type_code = None
+        if type_code in json_type_codes:
+            json_indexes.append(index)
+    return json_indexes
+
+
+def _deserialize_asyncmy_json_rows(
+    column_names: "list[str]",
+    rows: "list[dict[str, Any]]",
+    json_indexes: "list[int]",
+    deserializer: "Callable[[Any], Any]",
+    *,
+    logger: Any | None = None,
+) -> "list[dict[str, Any]]":
+    """Apply JSON deserialization to selected columns.
+
+    Args:
+        column_names: Ordered column names from the cursor description.
+        rows: Result rows represented as dictionaries.
+        json_indexes: Column indexes to deserialize.
+        deserializer: Callable used to decode JSON values.
+        logger: Optional logger for debug output.
+
+    Returns:
+        Rows with JSON columns decoded when possible.
+    """
+    if not rows or not column_names or not json_indexes:
+        return rows
+
+    target_columns = [column_names[index] for index in json_indexes if index < len(column_names)]
+    if not target_columns:
+        return rows
+
+    for row in rows:
+        for column in target_columns:
+            if column not in row:
+                continue
+            raw_value = row[column]
+            if raw_value is None:
+                continue
+            if isinstance(raw_value, bytearray):
+                raw_value = bytes(raw_value)
+            if not isinstance(raw_value, (str, bytes)):
+                continue
+            try:
+                row[column] = deserializer(raw_value)
+            except Exception:
+                if logger is not None:
+                    logger.debug("Failed to deserialize JSON column %s", column, exc_info=True)
+    return rows
+
+
+def collect_rows(
+    fetched_data: "Sequence[Any] | None",
+    description: "Sequence[Any] | None",
+    json_indexes: "list[int]",
+    deserializer: "Callable[[Any], Any]",
+    *,
+    logger: Any | None = None,
+) -> "tuple[list[dict[str, Any]], list[str]]":
+    """Collect AsyncMy rows into dictionaries with JSON decoding.
+
+    Args:
+        fetched_data: Rows returned from cursor.fetchall().
+        description: Cursor description metadata.
+        json_indexes: Column indexes containing JSON values.
+        deserializer: JSON deserializer function.
+        logger: Optional logger for debug output.
+
+    Returns:
+        Tuple of (rows, column_names).
+    """
+    if not description:
+        return [], []
+    column_names = [desc[0] for desc in description]
+    if not fetched_data:
+        return [], column_names
+    if not isinstance(fetched_data[0], dict):
+        rows = [dict(zip(column_names, row, strict=False)) for row in fetched_data]
+    else:
+        rows = [dict(row) for row in fetched_data]
+    rows = _deserialize_asyncmy_json_rows(column_names, rows, json_indexes, deserializer, logger=logger)
+    return rows, column_names
+
+
+def resolve_rowcount(cursor: Any) -> int:
+    """Resolve rowcount from an AsyncMy cursor.
+
+    Args:
+        cursor: AsyncMy cursor with optional rowcount metadata.
+
+    Returns:
+        Rowcount value or 0 when unknown.
+    """
+    if not has_rowcount(cursor):
+        return 0
+    rowcount = cursor.rowcount
+    if isinstance(rowcount, int) and rowcount >= 0:
+        return rowcount
+    return 0
+
+
+def normalize_lastrowid(cursor: Any) -> int | None:
+    """Normalize lastrowid for AsyncMy when rowcount indicates success.
+
+    Args:
+        cursor: AsyncMy cursor with optional lastrowid metadata.
+
+    Returns:
+        Last inserted id or None when unavailable.
+    """
+    if not has_rowcount(cursor):
+        return None
+    rowcount = cursor.rowcount
+    if not isinstance(rowcount, int) or rowcount <= 0:
+        return None
+    if not has_lastrowid(cursor):
+        return None
+    last_id = cursor.lastrowid
+    return last_id if isinstance(last_id, int) else None