Skip to content

asyncmy Adapter

from sqlspec.adapters.asyncmy import (
    AsyncmyConfig,
    AsyncmyConnectionParams,
    AsyncmyDriver,
    AsyncmyDriverFeatures,
    AsyncmyExceptionHandler,
    AsyncmyPoolParams,
)

Asynchronous MySQL and MariaDB adapter built on asyncmy. Inherited execution methods are documented on AsyncDriverAdapterBase. See the MySQL & MariaDB Setup Guide for usage examples.

Configuration & Parameters

AsyncmyConfig

Bases: AsyncDatabaseConfig[AsyncmyConnection, 'AsyncmyPool', AsyncmyDriver]

Configuration for Asyncmy database connections.

AsyncmyConnectionParams

Bases: TypedDict

Asyncmy connection parameters.

Attributes:

Name Type Description
dsn NotRequired[str]

MySQL/MariaDB connection URI (mysql://user:pass@host:port/db).
url NotRequired[str]

Connection URL alias parsed identically to dsn.
connection_string NotRequired[str]

Connection string alias parsed identically to dsn.
host NotRequired[str]

MySQL or MariaDB server hostname (defaults to 'localhost').
user NotRequired[str]

Database account username.
username NotRequired[str]

Alias normalized to user when user is omitted.
password NotRequired[str]

Password for the database user.
database NotRequired[str]

Default schema/database selected upon connecting.
db NotRequired[str]

Alias for database accepted by asyncmy.
port NotRequired[int]

MySQL/MariaDB TCP port (defaults to 3306).
unix_socket NotRequired[str]

Filesystem path to a local MySQL Unix domain socket.
charset NotRequired[str]

Connection character set (defaults to 'utf8mb4').
connect_timeout NotRequired[int | float]

TCP handshake and authentication timeout in seconds.
read_default_file NotRequired[str]

Path to a MySQL my.cnf option file.
read_default_group NotRequired[str]

Option group name read from read_default_file.
autocommit NotRequired[bool]

Enable MySQL autocommit mode on new connections.
allow_local_infile NotRequired[bool]

Permit client-side LOAD DATA LOCAL INFILE transfers.
local_infile NotRequired[bool]

Alias enabling LOAD DATA LOCAL INFILE support.
ssl NotRequired[AsyncmySSLParams | SSLContext | dict[str, Any]]

TLS configuration mapping or ssl.SSLContext instance.
sql_mode NotRequired[str]

Session sql_mode string applied when the connection opens.
init_command NotRequired[str]

SQL statement executed immediately after authentication.
auth_plugin_map NotRequired[dict[str | bytes, type[Any]]]

Mapping from MySQL auth plugin names to custom handler classes.
binary_prefix NotRequired[bool]

Emit _binary introducer prefixes when escaping bytes literals.
client_flag NotRequired[int]

Bitmask of MySQL CLIENT_* protocol capability flags.
conv NotRequired[dict[Any, Any]]

Custom MySQL field-type conversion table.
cursor_class NotRequired[type[AsyncmyRawCursor] | type[AsyncmyDictCursor]]

Cursor class alias normalized for asyncmy connections.
cursor_cls NotRequired[type[AsyncmyRawCursor] | type[AsyncmyDictCursor]]

Default asyncmy cursor class used by raw connections.
max_allowed_packet NotRequired[int]

Maximum client packet size in bytes (defaults to 16 MiB in asyncmy).
program_name NotRequired[str]

Client program name reported in performance_schema.session_connect_attrs.
read_timeout NotRequired[int | float]

Socket read timeout in seconds for query responses.
server_public_key NotRequired[str | bytes]

RSA public key PEM used for caching_sha2_password / sha256_password exchange.
stmt_cache_size NotRequired[int]

Maximum prepared statements cached per asyncmy connection.
use_unicode NotRequired[bool]

Decode string columns into Python str values (defaults to True).
write_timeout NotRequired[int | float]

Socket write timeout in seconds for outgoing packets.
extra NotRequired[dict[str, Any]]

Additional keyword arguments forwarded to asyncmy.connect / create_pool.

AsyncmyPoolParams

Bases: AsyncmyConnectionParams

Asyncmy pool parameters.

Attributes:

Name Type Description
minsize NotRequired[int]

Minimum number of open connections maintained in asyncmy.Pool.
maxsize NotRequired[int]

Maximum number of concurrent connections allowed in asyncmy.Pool.
echo NotRequired[bool]

Log executed SQL statements on asyncmy connections and pools.
pool_recycle NotRequired[int]

Maximum connection age in seconds before asyncmy recycles pooled connections.

AsyncmyDriverFeatures

Bases: TypedDict

Optional Asyncmy driver feature flags for JSON serialization, bulk loading, and events.

Attributes:

Name Type Description
enable_local_infile_bulk_load NotRequired[bool]

Use LOAD DATA LOCAL INFILE for load_from_arrow when local infile is enabled on the connection.
json_serializer NotRequired[Callable[[Any], str]]

Custom JSON serializer applied to bound JSON parameters (defaults to to_json).
json_deserializer NotRequired[Callable[[str], Any]]

Custom JSON deserializer applied to JSON result columns (defaults to from_json).
on_connection_create NotRequired[Callable[[AsyncmyConnection], Awaitable[None]]]

Async callback invoked once per physical asyncmy connection acquired from the pool.
enable_events NotRequired[bool]

Enable durable table-backed SQLSpec event queue support.
events_backend NotRequired[Literal['poll_queue']]

Event channel backend (poll_queue is the sole MySQL/MariaDB backend).

Driver & Pool

AsyncmyDriver

Bases: AsyncDriverAdapterBase

MySQL/MariaDB database driver using AsyncMy client library.

Implements asynchronous database operations for MySQL and MariaDB servers with support for parameter style conversion, type coercion, error handling, and transaction management.

AsyncmyExceptionHandler

Bases: BaseAsyncExceptionHandler

Async context manager for handling asyncmy (MySQL) database exceptions.

Maps MySQL error codes and SQLSTATE values to SQLSpec exceptions stored on pending_exception.

Extension Stores

AsyncmyStore

Bases: BaseSQLSpecStore['AsyncmyConfig']

MySQL/MariaDB session store using AsyncMy driver.

Implements server-side session storage for Litestar using MySQL/MariaDB via the AsyncMy driver. Provides efficient session management with: - Native async MySQL operations - UPSERT support using ON DUPLICATE KEY UPDATE - Automatic expiration handling - Efficient cleanup of expired sessions - Timezone-aware expiration (stored as UTC in DATETIME)

Parameters:

Name Type Description Default
config AsyncmyConfig

AsyncmyConfig instance.

 required

AsyncmyADKStore

Bases: BaseAsyncADKStore['AsyncmyConfig']

MySQL/MariaDB ADK store using AsyncMy driver.

AsyncmyADKMemoryStore

Bases: BaseAsyncADKMemoryStore['AsyncmyConfig']

MySQL/MariaDB ADK memory store using AsyncMy driver.

AsyncmyEventQueueStore

Bases: BaseEventQueueStore[AsyncmyConfig]

MySQL-specific event queue store.

Generates DDL optimized for MySQL 5.7.8+ using native JSON type. Index creation emits a plain ADD INDEX statement; the migration gates it on a data_dictionary.get_indexes check since MySQL has no idempotent CREATE INDEX IF NOT EXISTS.

Parameters:

Name Type Description Default
config ConfigT

AsyncmyConfig with extension_config["events"] settings.

 required