Skip to content

asyncmy Adapter

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

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

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.

reset_session_on_release NotRequired[bool]

Send COM_RESET_CONNECTION and re-initialize each connection when it is released (defaults to False).

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).

AsyncmySSLParams

Bases: TypedDict

Asyncmy TLS parameters.

Attributes:

Name Type Description
ca NotRequired[str]

Path to the PEM CA bundle file used to verify server certificates.

capath NotRequired[str]

Directory path containing hashed CA certificate files.

cert NotRequired[str]

Path to the client TLS certificate file.

key NotRequired[str]

Path to the client TLS private key file.

cipher NotRequired[str]

OpenSSL cipher suite list string.

check_hostname NotRequired[bool]

Verify that the server certificate matches the target hostname.

verify_mode NotRequired[bool | int | str]

Certificate verification policy (ssl.VerifyMode, boolean, or mode name).

Driver, Pool & Data Dictionary

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.

AsyncmyDataDictionary

Bases: MySQLAsyncDataDictionary

MySQL-specific async data dictionary for asyncmy.

Extension Stores & Configs

AsyncmyLitestarConfig

Bases: LitestarConfig

Asyncmy-specific Litestar settings.

Use inside extension_config["litestar"] with this adapter's session store.

Attributes:

Name Type Description
table_options NotRequired[str]

Table DDL options.

index_options NotRequired[str]

Index DDL options.

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

AsyncmyADKConfig

Bases: ADKConfig

asyncmy-specific ADK extension settings.

Use these keys inside extension_config["adk"] with the asyncmy ADK store.

Attributes:

Name Type Description
enable_event_generated_columns NotRequired[bool]

Create MySQL generated columns and indexes for common ADK event JSON paths.

enable_covering_indexes NotRequired[bool]

Add hot-path payload columns to MySQL ADK event replay indexes.

session_table_options NotRequired[str]

Raw MySQL table options appended to the ADK session table.

events_table_options NotRequired[str]

Raw MySQL table options appended to the ADK events table.

app_state_table_options NotRequired[str]

Raw MySQL table options appended to the ADK app state table.

user_state_table_options NotRequired[str]

Raw MySQL table options appended to the ADK user state table.

memory_table_options NotRequired[str]

Raw MySQL table options appended to the ADK memory table.

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