Add Connection.reset() using COM_RESET_CONNECTION

[methane]

Add Connection.reset() for explicitly clearing session state while retaining the authenticated connection. It returns None, uses mysql_reset_connection() / COM_RESET_CONNECTION, rolls back pending work, and leaves session options at the server's reset defaults without replaying constructor options or init_command.

The C call holds the connection lock and releases the GIL. Native failures use the existing exception translation. Reset suppresses automatic reconnect even after ping(True) or Connector/C option-file configuration, rejects pending results consistently across both client libraries, and has no fallback reset command. Builds without the API raise NotSupportedError rather than requiring a newer library for other operations: Oracle client headers >= 5.7.3, or MariaDB Connector/C package version >= 3.0.0 (not its server-version macro).

Reset reapplies the current client charset and the collation explicitly configured through the constructor or set_character_set(), matching PyMySQL PR #1283. A subsequent charset change without a collation clears that explicit setting and selects the charset's default. Arbitrary SQL changes are not tracked or inferred. Both restoration steps remain inside the native reset lock and reconnect suppression; either failure closes the connection and propagates the native exception. The public method takes no arguments; a private C helper accepts the retained collation. messages is cleared, while converter/cursor configuration is retained.

Autocommit remains native behavior. MySQL 8.4.11 resets @@session.autocommit to OFF when global autocommit is OFF, but returns the ON protocol status flag. A standalone C reproducer confirms this with both client libraries, including on fresh connections before any reset. The wrapper and charset restoration do not introduce it. The server unconditionally sets server_status = SERVER_STATUS_AUTOCOMMIT in THD::init(). Runtime-confirmed on 8.4.11; the same source pattern exists in 5.7.44 and 8.0.44, which were not run locally. This PR documents the limitation and follows native status without silently normalizing it. The autocommit test marks this specific inconsistent configuration as an expected failure. MariaDB's status agrees with its global value in both configurations.

Validation (Python 3.12.14):

• pytest --cov=MySQLdb tests / pytest -q tests: 168 passed using MariaDB Connector/C 3.4.9 against both MySQL Server 8.4.11 and MariaDB Server 11.8.6; 167 passed, 1 skipped using MySQL libmysqlclient 8.4.11 against both servers (the skip is the Connector/C-specific option-file test).
• Tests cover repeated reuse, rollback with InnoDB, temporary tables, session/user variables, named locks, identity/database retention, autocommit cache, utf8mb4/latin1/GBK escaping and decoding, constructor/setter collation preservation, subsequent charset changes, failed collation changes, restoration failure closure, closed/killed connections, reconnect suppression, pending/streaming results and concurrent access.
• Nondefault global autocommit OFF: MariaDB 3 passed; MySQL 3 expected failures for the documented server inconsistency.
• Temporary native fault injection verified charset-restoration errors retain their native error and close the connection. Integration tests verify collation-restoration errors close the connection with reconnect either enabled or disabled.
• Forced compilation of the unsupported Connector/C version branch verified NotSupportedError without changing session collation. This is branch coverage, not testing a real old client library.
• ruff format on changed Python files; ruff check src tests/test_connection.py tests/test_reset.py; git diff --check.

Historical client/server versions remain untested locally. CI is green on 3818f0c55ff2c4537768ad48e41a333a7916a693: all seven Python test jobs, Django LTS, Windows x64 and ARM64 wheel builds, lint and Read the Docs passed. CodeRabbit skipped review because the PR is a draft. No automatic reset/ping strategy, Aurora checks, or server autocommit workaround is included.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}