Add Connection.reset() using COM_RESET_CONNECTION

[methane]

Add Connection.reset() for explicit reuse of an existing session. It sends COM_RESET_CONNECTION, consumes the OK/error response through the existing protocol helpers, and returns None like commit() and rollback().

The reset rolls back outstanding work and restores server session defaults, including autocommit. It does not replay constructor autocommit, sql_mode, or init_command, reconnect, authenticate again, or fall back to another reset command. The current database is retained. Server status flags and cached autocommit follow the protocol response; affected-row count and connection result/insert-id state are cleared. See the MySQL global-autocommit-OFF limitation below. Existing command handling drains pending results; documentation tells callers to close old cursors before reuse.

Charset semantics are intentional: a raw reset also resets charset session variables, so this method reapplies PyMySQL's current charset/collation with SET NAMES. This keeps the client encoder and server aligned, including after set_character_set(). A failure in that step closes the connection and propagates the error. See the MySQL reset specification.

The command was introduced in MySQL 5.7.3 / MariaDB 10.2.4; the project's supported-server policy is unchanged. No pool policy, automatic ping/reset strategy, or Aurora checks are added.

Validation:

• Full integration suite on Python 3.12 (pytest -q pymysql, also previously run with CI coverage options): MariaDB 11.8.6 — 204 passed, 11 skipped, 1 xfailed; MySQL 8.4.11 — 203 passed, 12 skipped, 1 xfailed.
• 18 new tests cover wire command/response handling, rollback and successful reuse, session cleanup/defaults, retained database, charset/collation and non-ASCII round trips, result draining, closed connections, server errors, transport errors, and failed charset restoration. All 18 also pass on Python 3.9 / MariaDB 11.8.6.
• Converter doctests: 4 passed. MySQL authentication tests: 8 passed.
• ruff format, ruff check, and git diff --check pass.
• Sphinx build with warnings treated as errors passes with -D html_static_path= (the repository's configured _static directory is absent).

Other database versions and PyPy were not run locally; the existing CI matrix covers additional versions. Unsupported-server behavior is exercised with a protocol error fixture, not an old database installation.

Post-publication verification: remote branch and PR head both match ca330a03d62aeb24f2d242bfa78c69c510347fbe. All nine jobs in the PR test matrix and the corresponding push matrix passed: MySQL 5.7/8.0/8.4/9 and MariaDB 10.6/10.11/11.4/11.8/12, with Python 3.9–3.14 and PyPy 3.11. Lint, CodeQL, and Read the Docs also passed. No CI fixes were necessary.

Follow-up investigation (commit b3044a28455854893903bd977d7ec37f39340523): reproduced the same MySQL 8.4.11 global-autocommit-OFF inconsistency reported by mysqlclient #805. The session variable is OFF and inserts remain uncommitted, while reset, charset restoration, and later queries report the ON protocol flag. PyMySQL's get_autocommit() therefore reports True; autocommit(True) may skip its command because it trusts the flag. Fresh connections without calling reset show the same problem, so this is not introduced by the PR. No-op SET autocommit=0 or SET autocommit=@@SESSION.autocommit does not repair the server status. The method keeps native semantics rather than adding a server workaround; docs and tests now expose the limitation.

Only isolated test servers were changed, with original global values restored in finally. With global autocommit OFF, all 18 reset tests pass on MariaDB 11.8.6; MySQL 8.4.11 has 15 passes and 3 targeted expected failures (constructor autocommit False/True/None). With global autocommit ON, all 18 pass on both servers.

Final follow-up CI verification: all nine jobs in the updated PR matrix passed on b3044a28455854893903bd977d7ec37f39340523, as did the push matrix, lint, CodeQL, and Read the Docs. The PR remains a draft.

[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.}