pymysql Adapter¶

from sqlspec.adapters.pymysql import (
    PyMysqlConfig,
    PyMysqlConnectionParams,
    PyMysqlDriver,
    PyMysqlDriverFeatures,
    PyMysqlExceptionHandler,
    PyMysqlPoolParams,
)

Synchronous MySQL and MariaDB adapter built on pymysql. Inherited execution methods are documented on SyncDriverAdapterBase. See the MySQL & MariaDB Setup Guide for usage examples.

Configuration & Parameters¶

PyMysqlConfig ¶

Bases: SyncDatabaseConfig[PyMysqlConnection, PyMysqlConnectionPool, PyMysqlDriver]

Configuration for PyMySQL synchronous connections.

`PyMysqlConnectionParams` ¶

Bases: TypedDict

PyMySQL 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 `pymysql.connect`.
`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'`).
`collation`	`NotRequired[str]`	Session collation paired with `charset`.
`sql_mode`	`NotRequired[str]`	Session `sql_mode` string applied when the connection opens.
`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`.
`conv`	`NotRequired[PyMysqlConverter]`	Custom PyMySQL type encoder/decoder mapping.
`use_unicode`	`NotRequired[bool]`	Decode text columns into Python `str` values (defaults to `True`).
`client_flag`	`NotRequired[int]`	Bitmask of MySQL `CLIENT_*` protocol capability flags.
`cursorclass`	`NotRequired[type[PyMysqlRawCursor]]`	Default PyMySQL cursor class instantiated by `conn.cursor()`.
`init_command`	`NotRequired[str]`	SQL statement executed immediately after authentication.
`connect_timeout`	`NotRequired[PyMysqlTimeout]`	TCP handshake and authentication timeout in seconds.
`read_timeout`	`NotRequired[PyMysqlTimeout]`	Socket read timeout in seconds for server responses.
`write_timeout`	`NotRequired[PyMysqlTimeout]`	Socket write timeout in seconds for outgoing packets.
`autocommit`	`NotRequired[bool]`	Enable MySQL autocommit mode on new connections.
`allow_local_infile`	`NotRequired[bool]`	Alias enabling `LOAD DATA LOCAL INFILE` transfers.
`local_infile`	`NotRequired[bool]`	Permit client-side `LOAD DATA LOCAL INFILE` transfers.
`max_allowed_packet`	`NotRequired[int]`	Maximum client packet size in bytes.
`defer_connect`	`NotRequired[bool]`	Construct the `pymysql.Connection` instance without opening the socket immediately.
`auth_plugin_map`	`NotRequired[Mapping[str, type[Any]]]`	Mapping from MySQL auth plugin names to custom handler classes.
`bind_address`	`NotRequired[str]`	Local source IP address or hostname bound by the client socket.
`binary_prefix`	`NotRequired[bool]`	Emit `_binary` introducer prefixes when escaping `bytes` literals.
`program_name`	`NotRequired[str]`	Application name sent in MySQL connection attributes.
`server_public_key`	`NotRequired[str \| bytes]`	Server RSA public key PEM used for SHA-256 password exchange.
`ssl`	`NotRequired[PyMysqlSslConfig]`	TLS `ssl.SSLContext` or `PyMysqlSslParams` mapping.
`ssl_ca`	`NotRequired[str]`	Path to the PEM CA bundle file for TLS verification.
`ssl_cert`	`NotRequired[str]`	Path to the client TLS certificate file.
`ssl_disabled`	`NotRequired[bool]`	Disable TLS negotiation completely when `True`.
`ssl_key`	`NotRequired[str]`	Path to the client TLS private key file.
`ssl_key_password`	`NotRequired[str]`	Passphrase unlocking an encrypted `ssl_key`.
`ssl_verify_cert`	`NotRequired[bool]`	Verify the server TLS certificate against `ssl_ca`.
`ssl_verify_identity`	`NotRequired[bool]`	Verify that the server TLS certificate matches the target hostname.
`extra`	`NotRequired[dict[str, Any]]`	Additional keyword arguments forwarded to `pymysql.connect`.

`PyMysqlPoolParams` ¶

Bases: PyMysqlConnectionParams

PyMySQL pool parameters.

Attributes:

Name	Type	Description
`pool_recycle_seconds`	`NotRequired[int]`	Maximum connection age in seconds before recycling pooled PyMySQL connections.
`health_check_interval`	`NotRequired[float]`	Minimum interval in seconds between `conn.ping()` liveness checks.

`PyMysqlDriverFeatures` ¶

Bases: TypedDict

Optional PyMySQL driver feature flags, Cloud SQL connector settings, and bulk-load options.

Attributes:

Name	Type	Description
`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[[PyMysqlConnection], None]]`	Synchronous hook invoked with each raw `pymysql.Connection` upon creation.
`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).
`enable_local_infile_bulk_load`	`NotRequired[bool]`	Route `load_from_arrow` through `LOAD DATA LOCAL INFILE` when local infile is enabled.
`enable_cloud_sql`	`NotRequired[bool]`	Route connections through `cloud-sql-python-connector` (defaults to `False`).
`cloud_sql_instance`	`NotRequired[str]`	Cloud SQL instance connection string in `project:region:instance` format.
`cloud_sql_enable_iam_auth`	`NotRequired[bool]`	Use IAM database authentication with the Cloud SQL Python Connector.
`cloud_sql_ip_type`	`NotRequired[str]`	Cloud SQL network path (`PUBLIC`, `PRIVATE`, or `PSC`; defaults to `PRIVATE`).

Driver & Pool¶

PyMysqlDriver ¶

Bases: SyncDriverAdapterBase

MySQL/MariaDB database driver using PyMySQL.

PyMysqlExceptionHandler ¶

Bases: BaseSyncExceptionHandler

Context manager for handling PyMySQL exceptions.

Extension Stores¶

PyMysqlStore ¶

Bases: BaseSQLSpecStore['PyMysqlConfig']

MySQL/MariaDB session store using PyMySQL sync driver.

PyMysqlADKStore ¶

Bases: BaseSyncADKStore['PyMysqlConfig']

MySQL/MariaDB ADK store using PyMySQL.

PyMysqlADKMemoryStore ¶

Bases: BaseSyncADKMemoryStore['PyMysqlConfig']

MySQL/MariaDB ADK memory store using PyMySQL.

PyMysqlEventQueueStore ¶

Bases: BaseEventQueueStore[PyMysqlConfig]

Queue DDL for PyMySQL configs.

pymysql Adapter¶

Configuration & Parameters¶

PyMysqlConfig ¶

PyMysqlConnectionParams ¶

PyMysqlPoolParams ¶

PyMysqlDriverFeatures ¶

Driver & Pool¶

PyMysqlDriver ¶

PyMysqlExceptionHandler ¶

Extension Stores¶

PyMysqlStore ¶

PyMysqlADKStore ¶

PyMysqlADKMemoryStore ¶

PyMysqlEventQueueStore ¶

`PyMysqlConnectionParams` ¶

`PyMysqlPoolParams` ¶

`PyMysqlDriverFeatures` ¶