PyMySQL is a pure-Python MySQL client library, fully compliant with PEP 249 (Python Database API Specification v2.0). It enables Python applications to connect to MySQL and MariaDB databases without requiring binary extensions. The library is actively maintained, with version 1.1.2 released on August 24, 2025, and supports standard DB-API 2.0 features like cursors, transactions, and parameterized queries.
pip install PyMySQLVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to establish a connection to a MySQL database, insert a record, commit the transaction, and fetch data using `pymysql`. It uses `DictCursor` for results as dictionaries and includes error handling and proper connection closing. Remember that `PyMySQL` does not autocommit by default, so explicit `connection.commit()` is necessary.
Ensure your project uses Python 3.6+ and update `pymysql.connect()` calls to use keyword arguments for all parameters, especially `database` and `password`. Review and update authentication methods if `old_password` was in use.
Always use a sequence (tuple or list) of parameters with `cursor.execute()` for parameterized queries. For example, `cursor.execute('INSERT INTO users VALUES (%s, %s)', (value1, value2))` is correct, `cursor.execute('INSERT INTO users VALUES (%(key1)s, %(key2)s)', {'key1': value1, 'key2': value2})` is now forbidden.Refer to error classes directly from the `pymysql` module (e.g., `pymysql.Error`). Avoid `Connection.set_charset()` and use `charset` parameter in `pymysql.connect()` instead. Update `connect()` calls to use `database` and `password` parameters.
Always call `connection.commit()` after performing data modification operations, or set `autocommit=True` when establishing the connection if that behavior is desired. Use `with connection:` for reliable connection handling which includes `commit()` on success or `rollback()` on exceptions.
Integrate a connection pooling library (e.g., `pip install DBUtils` and use `PooledDB` or `pip install pymysql-pool`) into your application architecture.
Implement connection `ping()` checks before executing queries (`connection.ping(reconnect=True)` can re-establish the connection if it dropped, though its default behavior has changed in related drivers). Consider increasing MySQL server's `wait_timeout` or `max_allowed_packet` if large queries are the cause. Use connection pooling to manage connection lifecycle effectively.
Ensure the MySQL server is running and accessible from the application's host. Verify the host, port, username, and password provided to `pymysql.connect()` are correct. Check firewall rules on both the client and server machines. If connecting to `localhost`, ensure the server is configured to accept local connections on the correct port (default is 3306).
Verify that the MySQL server is running and accessible from the client's host. Ensure the `host` and `port` parameters in `pymysql.connect()` are correct. Check server-side configuration (e.g., `bind-address` in `my.cnf` or `my.ini`) and firewall rules to allow incoming connections on the MySQL port (default 3306).
Install the 'pymysql' package using pip: `pip install pymysql`.
Verify the MySQL server is running, check the host address and port (default is 3306), ensure no firewalls are blocking the connection, and confirm the correct `host` and `port` in the `pymysql.connect()` call. Using '127.0.0.1' instead of 'localhost' can sometimes resolve the issue.
Change the MySQL user's authentication method to `mysql_native_password` using an SQL command: `ALTER USER 'your_user'@'localhost' IDENTIFIED WITH mysql_native_password BY 'your_password';`.
Ensure the database connection is successfully established by wrapping the connection attempt in a try-except block to catch `pymysql.err.OperationalError` or similar connection exceptions, and validate connection parameters (host, user, password, db) before attempting to create a cursor.
Increase MySQL server configuration parameters like `wait_timeout`, `interactive_timeout`, or `net_write_timeout` to allow longer idle connections. If dealing with large queries, increase `max_allowed_packet`. For very long operations, consider re-establishing the connection or sending keep-alive signals.