This document provides a technical overview of PyMySQL, a pure-Python MySQL and MariaDB client library that implements the Python Database API 2.0 specification. It covers PyMySQL's core purpose, key features, installation procedures, basic usage patterns, and high-level architecture.
For detailed information about specific subsystems, see the following related pages: Core Connection System, Authentication and Security, MySQL Protocol Implementation, DB-API 2.0 Compliance, and MySQLdb Compatibility.
PyMySQL is a pure-Python MySQL client library that provides database connectivity without requiring any C extensions or external dependencies beyond the Python standard library. It serves as a drop-in replacement for MySQLdb and implements the Python Database API 2.0 specification for database interfacing.
Key Characteristics:
caching_sha2_passwordSources: pymysql/__init__.py1-23 README.md1-17
| Component | Supported Versions |
|---|---|
| Python | CPython 3.9+ or latest PyPy 3.x |
| MySQL Server | MySQL LTS versions (5.7+) |
| MariaDB Server | MariaDB LTS versions (10.3+) |
Basic Installation:
With RSA Authentication Support:
With MariaDB ed25519 Authentication:
The optional dependencies enable support for advanced authentication methods that require cryptographic libraries.
Sources: README.md19-35 docs/source/user/installation.rst7-14
Sources: README.md44-90 example.py1-18
The main entry point pymysql.connect() is an alias to connections.Connection, which handles the actual database connection logic. The public API exposes DB-API 2.0 compliant interfaces and type objects.
Sources: pymysql/__init__.py136 pymysql/__init__.py28-40 pymysql/__init__.py99-124
PyMySQL implements the Python Database API 2.0 specification with the following compliance parameters:
| Parameter | Value | Description |
|---|---|---|
apilevel | "2.0" | DB-API version supported |
threadsafety | 1 | Module is thread-safe at connection level |
paramstyle | "pyformat" | Parameter style (e.g., %(name)s) |
The DBAPISet class provides enhanced set operations for type checking, allowing both set-style comparisons and membership testing against individual values.
Sources: pymysql/__init__.py75-77 pymysql/__init__.py82-97 pymysql/__init__.py99-124
PyMySQL provides backward compatibility with the MySQLdb library through several mechanisms:
The install_as_MySQLdb() function enables transparent replacement of MySQLdb:
Sources: pymysql/__init__.py52-58 pymysql/__init__.py65-71
The architecture follows a layered design where the public API in __init__.py delegates to specialized modules for connection management, query execution, data conversion, and protocol handling.
Sources: pymysql/__init__.py79 pymysql/__init__.py27 pymysql/__init__.py136
PyMySQL maintains dual versioning to support both its own development and compatibility with existing MySQLdb-dependent applications:
This dual versioning strategy allows PyMySQL to maintain compatibility with frameworks like Django that check for specific MySQLdb version ranges while still providing accurate version information for PyMySQL-specific use cases.
Sources: pymysql/__init__.py50-58
PyMySQL implements connection-level thread safety (threadsafety = 1), meaning:
thread_safe() returns True for MySQLdb compatibilityThe connection-level thread safety model requires applications to implement their own connection pooling or ensure proper locking when sharing connections across threads.
Refresh this wiki