mysql-connector-python

Official MySQL driver with both sync and async support.

Sync Configuration

class sqlspec.adapters.mysqlconnector.MysqlConnectorSyncConfig

Bases: SyncDatabaseConfig[MySQLConnection, MysqlConnectorConnectionPool, MysqlConnectorSyncDriver]

Configuration for mysql-connector synchronous MySQL connections.

driver_type

alias of MysqlConnectorSyncDriver

connection_type

alias of MySQLConnection

__init__(*, connection_config=None, connection_instance=None, migration_config=None, statement_config=None, driver_features=None, bind_key=None, extension_config=None, observability_config=None, **kwargs)

create_connection()

Create a database connection.

Return type:

MySQLConnection

get_signature_namespace()

Get the signature namespace for this database configuration.

Returns a dictionary of type names to objects (classes, functions, or other callables) that should be registered with Litestar's signature namespace to prevent serialization attempts on database-specific structures.

Return type:

dict[str, typing.Any]

Returns:

Dictionary mapping type names to objects.

get_event_runtime_hints()

Return default event runtime hints for this configuration.

Return type:

EventRuntimeHints

Async Configuration

class sqlspec.adapters.mysqlconnector.MysqlConnectorAsyncConfig

Bases: NoPoolAsyncConfig[MySQLConnection, MysqlConnectorAsyncDriver]

Configuration for mysql-connector async MySQL connections.

driver_type

alias of MysqlConnectorAsyncDriver

connection_type

alias of MySQLConnection

__init__(*, connection_config=None, connection_instance=None, migration_config=None, statement_config=None, driver_features=None, bind_key=None, extension_config=None, observability_config=None, **kwargs)

async create_connection()

Create a database connection.

Return type:

MySQLConnection

provide_connection(*args, **kwargs)

Provide a database connection context manager.

Return type:

MysqlConnectorAsyncConnectionContext

provide_session(*_args, statement_config=None, **_kwargs)

Provide a database session context manager.

Return type:

MysqlConnectorAsyncSessionContext

get_signature_namespace()

Get the signature namespace for this database configuration.

Returns a dictionary of type names to objects (classes, functions, or other callables) that should be registered with Litestar's signature namespace to prevent serialization attempts on database-specific structures.

Return type:

dict[str, typing.Any]

Returns:

Dictionary mapping type names to objects.

get_event_runtime_hints()

Return default event runtime hints for this configuration.

Return type:

EventRuntimeHints

Sync Driver

class sqlspec.adapters.mysqlconnector.MysqlConnectorSyncDriver

Bases: SyncDriverAdapterBase

MySQL/MariaDB database driver using mysql-connector sync library.

__init__(connection, statement_config=None, driver_features=None)

Initialize driver adapter with connection and configuration.

Parameters:

• connection (MySQLConnection) -- Database connection instance

• statement_config (StatementConfig | None) -- Statement configuration for the driver

• driver_features (dict[str, typing.Any] | None) -- Driver-specific features like extensions, secrets, and connection callbacks

• observability -- Optional runtime handling lifecycle hooks, observers, and spans

dispatch_execute(cursor, statement)

Execute a single SQL statement.

Must be implemented by each driver for database-specific execution logic.

Parameters:

• cursor (Any) -- Database cursor/connection object

• statement (SQL) -- SQL statement object with all necessary data and configuration

Return type:

ExecutionResult

Returns:

ExecutionResult with execution data

dispatch_execute_many(cursor, statement)

Execute SQL with multiple parameter sets (executemany).

Must be implemented by each driver for database-specific executemany logic.

Parameters:

• cursor (Any) -- Database cursor/connection object

• statement (SQL) -- SQL statement object with all necessary data and configuration

Return type:

ExecutionResult

Returns:

ExecutionResult with execution data for the many operation

dispatch_execute_script(cursor, statement)

Execute a SQL script containing multiple statements.

Default implementation splits the script and executes statements individually. Drivers can override for database-specific script execution methods.

Parameters:

• cursor (Any) -- Database cursor/connection object

• statement (SQL) -- SQL statement object with all necessary data and configuration

Return type:

ExecutionResult

Returns:

ExecutionResult with script execution data including statement counts

begin()

Begin a database transaction on the current connection.

Return type:

None

commit()

Commit the current transaction on the current connection.

Return type:

None

rollback()

Rollback the current transaction on the current connection.

Return type:

None

with_cursor(connection)

Create and return a context manager for cursor acquisition and cleanup.

Returns a context manager that yields a cursor for database operations. Concrete implementations handle database-specific cursor creation and cleanup.

Return type:

MysqlConnectorSyncCursor

dispatch_select_stream(statement, chunk_size)

Return a native mysql-connector row stream backed by an unbuffered cursor.

Return type:

Optional[SyncRowStream[dict[str, typing.Any]]]

handle_database_exceptions()

Handle database-specific exceptions and wrap them appropriately.

Return type:

MysqlConnectorSyncExceptionHandler

Returns:

Exception handler with deferred exception pattern for mypyc compatibility. The handler stores mapped exceptions in pending_exception rather than raising from __exit__ to avoid ABI boundary violations.

select_to_storage(statement, destination, /, *parameters, statement_config=None, partitioner=None, format_hint=None, telemetry=None, **kwargs)

Stream a SELECT statement directly into storage.

Parameters:

• statement (SQL | str) -- SQL statement to execute.

• destination (str | Path) -- Storage destination path.

• parameters (Any) -- Query parameters.

• statement_config (StatementConfig | None) -- Optional statement configuration.

• partitioner (dict[str, object] | None) -- Optional partitioner configuration.

• format_hint (Optional[Literal['jsonl', 'json', 'parquet', 'arrow-ipc', 'csv']]) -- Optional format hint for storage.

• telemetry (StorageTelemetry | None) -- Optional telemetry dict to merge.

Return type:

StorageBridgeJob

Returns:

StorageBridgeJob with execution telemetry.

load_from_arrow(table, source, *, partitioner=None, overwrite=False, telemetry=None)

Load Arrow data into the target table.

Parameters:

• table (str) -- Target table name.

• source (Union[ArrowResult, typing.Any]) -- Arrow data source.

• partitioner (dict[str, object] | None) -- Optional partitioner configuration.

• overwrite (bool) -- Whether to overwrite existing data.

Return type:

StorageBridgeJob

Returns:

StorageBridgeJob with execution telemetry.

load_from_storage(table, source, *, file_format, partitioner=None, overwrite=False)

Load artifacts from storage into the target table.

Parameters:

• table (str) -- Target table name.

• source (str | Path) -- Storage source path.

• file_format (Literal['jsonl', 'json', 'parquet', 'arrow-ipc', 'csv']) -- File format of source.

• partitioner (dict[str, object] | None) -- Optional partitioner configuration.

• overwrite (bool) -- Whether to overwrite existing data.

Return type:

StorageBridgeJob

Returns:

StorageBridgeJob with execution telemetry.

property data_dictionary: MysqlConnectorSyncDataDictionary

Get the data dictionary for this driver.

Returns:

Data dictionary instance for metadata queries

collect_rows(cursor, fetched)

Collect mysql-connector sync rows for the direct execution path.

Return type:

tuple[list[typing.Any], list[str], int]

resolve_rowcount(cursor)

Resolve rowcount from mysql-connector cursor for the direct execution path.

Return type:

int

Async Driver

class sqlspec.adapters.mysqlconnector.MysqlConnectorAsyncDriver

Bases: AsyncDriverAdapterBase

MySQL/MariaDB database driver using mysql-connector async library.

__init__(connection, statement_config=None, driver_features=None)

Initialize driver adapter with connection and configuration.

Parameters:

• connection (MySQLConnection) -- Database connection instance

• statement_config (StatementConfig | None) -- Statement configuration for the driver

• driver_features (dict[str, typing.Any] | None) -- Driver-specific features like extensions, secrets, and connection callbacks

• observability -- Optional runtime handling lifecycle hooks, observers, and spans

async dispatch_execute(cursor, statement)

Execute a single SQL statement.

Must be implemented by each driver for database-specific execution logic.

Parameters:

• cursor (Any) -- Database cursor/connection object

• statement (SQL) -- SQL statement object with all necessary data and configuration

Return type:

ExecutionResult

Returns:

ExecutionResult with execution data

async dispatch_execute_many(cursor, statement)

Execute SQL with multiple parameter sets (executemany).

Must be implemented by each driver for database-specific executemany logic.

Parameters:

• cursor (Any) -- Database cursor/connection object

• statement (SQL) -- SQL statement object with all necessary data and configuration

Return type:

ExecutionResult

Returns:

ExecutionResult with execution data for the many operation

async dispatch_execute_script(cursor, statement)

Execute a SQL script containing multiple statements.

Default implementation splits the script and executes statements individually. Drivers can override for database-specific script execution methods.

Parameters:

• cursor (Any) -- Database cursor/connection object

• statement (SQL) -- SQL statement object with all necessary data and configuration

Return type:

ExecutionResult

Returns:

ExecutionResult with script execution data including statement counts

async begin()

Begin a database transaction on the current connection.

Return type:

None

async commit()

Commit the current transaction on the current connection.

Return type:

None

async rollback()

Rollback the current transaction on the current connection.

Return type:

None

with_cursor(connection)

Create and return an async context manager for cursor acquisition and cleanup.

Returns an async context manager that yields a cursor for database operations. Concrete implementations handle database-specific cursor creation and cleanup.

Return type:

MysqlConnectorAsyncCursor

dispatch_select_stream(statement, chunk_size)

Return a native mysql-connector row stream backed by an unbuffered cursor.

Return type:

Optional[AsyncRowStream[dict[str, typing.Any]]]

handle_database_exceptions()

Handle database-specific exceptions and wrap them appropriately.

Return type:

MysqlConnectorAsyncExceptionHandler

Returns:

Exception handler with deferred exception pattern for mypyc compatibility. The handler stores mapped exceptions in pending_exception rather than raising from __aexit__ to avoid ABI boundary violations.

async select_to_storage(statement, destination, /, *parameters, statement_config=None, partitioner=None, format_hint=None, telemetry=None, **kwargs)

Stream a SELECT statement directly into storage.

Parameters:

• statement (SQL | str) -- SQL statement to execute.

• destination (str | Path) -- Storage destination path.

• parameters (Any) -- Query parameters.

• statement_config (StatementConfig | None) -- Optional statement configuration.

• partitioner (dict[str, object] | None) -- Optional partitioner configuration.

• format_hint (Optional[Literal['jsonl', 'json', 'parquet', 'arrow-ipc', 'csv']]) -- Optional format hint for storage.

• telemetry (StorageTelemetry | None) -- Optional telemetry dict to merge.

Return type:

StorageBridgeJob

Returns:

StorageBridgeJob with execution telemetry.

async load_from_arrow(table, source, *, partitioner=None, overwrite=False, telemetry=None)

Load Arrow data into the target table.

Parameters:

• table (str) -- Target table name.

• source (Union[ArrowResult, typing.Any]) -- Arrow data source.

• partitioner (dict[str, object] | None) -- Optional partitioner configuration.

• overwrite (bool) -- Whether to overwrite existing data.

Return type:

StorageBridgeJob

Returns:

StorageBridgeJob with execution telemetry.

Raises:

NotImplementedError -- If not implemented.

async load_from_storage(table, source, *, file_format, partitioner=None, overwrite=False)

Load artifacts from storage into the target table.

Parameters:

• table (str) -- Target table name.

• source (str | Path) -- Storage source path.

• file_format (Literal['jsonl', 'json', 'parquet', 'arrow-ipc', 'csv']) -- File format of source.

• partitioner (dict[str, object] | None) -- Optional partitioner configuration.

• overwrite (bool) -- Whether to overwrite existing data.

Return type:

StorageBridgeJob

Returns:

StorageBridgeJob with execution telemetry.

property data_dictionary: MysqlConnectorAsyncDataDictionary

Get the data dictionary for this driver.

Returns:

Data dictionary instance for metadata queries

collect_rows(cursor, fetched)

Collect mysql-connector async rows for the direct execution path.

Return type:

tuple[list[typing.Any], list[str], int]

resolve_rowcount(cursor)

Resolve rowcount from mysql-connector cursor for the direct execution path.

Return type:

int

Sync Data Dictionary

class sqlspec.adapters.mysqlconnector.data_dictionary.MysqlConnectorSyncDataDictionary

Bases: SyncDataDictionaryBase

MySQL-specific sync data dictionary.

dialect: ClassVar[str] = 'mysql'

Dialect identifier. Must be defined by subclasses as a class attribute.

__init__()

get_version(driver)

Get MySQL database version information.

Return type:

VersionInfo | None

get_feature_flag(driver, feature)

Check if MySQL database supports a specific feature.

Return type:

bool

get_metadata_capabilities(driver, domains=None)

Get data-dictionary capability profile.

Return type:

MetadataCapabilityProfile

get_schemas(driver)

Get schema metadata from INFORMATION_SCHEMA.

Return type:

MetadataResult

get_objects(driver, schema=None)

Get object metadata from INFORMATION_SCHEMA.

Return type:

MetadataResult

get_table_details(driver, table, schema=None)

Get rich table metadata from INFORMATION_SCHEMA.

Return type:

MetadataResult

get_constraints(driver, table=None, schema=None)

Get constraint metadata from INFORMATION_SCHEMA.

Return type:

MetadataResult

get_views(driver, schema=None)

Get view metadata from INFORMATION_SCHEMA.

Return type:

MetadataResult

get_routines(driver, schema=None)

Get routine metadata from INFORMATION_SCHEMA.

Return type:

MetadataResult

get_privileges(driver, object_name=None, schema=None)

Get privilege metadata from INFORMATION_SCHEMA.

Return type:

MetadataResult

get_ddl(driver, object_name, schema=None, *, object_type='table', include_dependencies=True, prefer_native=True, redact=True)

Get native SHOW CREATE output and replay-sensitive context for a table.

Return type:

DDLResult

get_system_metadata(driver, request=None, **kwargs)

Get opt-in system metadata from performance_schema or sys.

Return type:

SystemMetadataResult

get_optimal_type(driver, type_category)

Get optimal MySQL type for a category.

Return type:

str

get_tables(driver, schema=None)

Get tables sorted by topological dependency order using the MySQL catalog.

Return type:

list[TableMetadata]

get_columns(driver, table=None, schema=None)

Get column information for a table or schema.

Return type:

list[ColumnMetadata]

get_indexes(driver, table=None, schema=None)

Get index metadata for a table or schema.

Return type:

list[IndexMetadata]

get_foreign_keys(driver, table=None, schema=None)

Get foreign key metadata.

Return type:

list[ForeignKeyMetadata]

Async Data Dictionary

class sqlspec.adapters.mysqlconnector.data_dictionary.MysqlConnectorAsyncDataDictionary

Bases: AsyncDataDictionaryBase

MySQL-specific async data dictionary.

dialect: ClassVar[str] = 'mysql'

Dialect identifier. Must be defined by subclasses as a class attribute.

__init__()

async get_version(driver)

Get MySQL database version information.

Return type:

VersionInfo | None

async get_feature_flag(driver, feature)

Check if MySQL database supports a specific feature.

Return type:

bool

async get_metadata_capabilities(driver, domains=None)

Get data-dictionary capability profile.

Return type:

MetadataCapabilityProfile

async get_schemas(driver)

Get schema metadata from INFORMATION_SCHEMA.

Return type:

MetadataResult

async get_objects(driver, schema=None)

Get object metadata from INFORMATION_SCHEMA.

Return type:

MetadataResult

async get_table_details(driver, table, schema=None)

Get rich table metadata from INFORMATION_SCHEMA.

Return type:

MetadataResult

async get_constraints(driver, table=None, schema=None)

Get constraint metadata from INFORMATION_SCHEMA.

Return type:

MetadataResult

async get_views(driver, schema=None)

Get view metadata from INFORMATION_SCHEMA.

Return type:

MetadataResult

async get_routines(driver, schema=None)

Get routine metadata from INFORMATION_SCHEMA.

Return type:

MetadataResult

async get_privileges(driver, object_name=None, schema=None)

Get privilege metadata from INFORMATION_SCHEMA.

Return type:

MetadataResult

async get_ddl(driver, object_name, schema=None, *, object_type='table', include_dependencies=True, prefer_native=True, redact=True)

Get native SHOW CREATE output and replay-sensitive context for a table.

Return type:

DDLResult

async get_system_metadata(driver, request=None, **kwargs)

Get opt-in system metadata from performance_schema or sys.

Return type:

SystemMetadataResult

async get_optimal_type(driver, type_category)

Get optimal MySQL type for a category.

Return type:

str

async get_tables(driver, schema=None)

Get tables sorted by topological dependency order using the MySQL catalog.

Return type:

list[TableMetadata]

async get_columns(driver, table=None, schema=None)

Get column information for a table or schema.

Return type:

list[ColumnMetadata]

async get_indexes(driver, table=None, schema=None)

Get index metadata for a table or schema.

Return type:

list[IndexMetadata]

async get_foreign_keys(driver, table=None, schema=None)

Get foreign key metadata.

Return type:

list[ForeignKeyMetadata]