fix(mysql): kill server-side query on timeout instead of leaking it into the pool

[tianzhou]

Summary

Fixes #384. query_timeout on the MySQL connector currently only aborts the client-side wait — the statement keeps running on the MySQL server, and worse, the pooled connection is silently handed back in a state that can hang the next unrelated caller.

Root cause: mysql2's timeout option is documented as client-side only (confirmed by the maintainer in sidorares/node-mysql2#185 and #789) — on timeout it rejects the query's own promise, but never tells the connection's internal command queue that the statement is done, and never notifies the server. Any command sent afterward on that same connection — including our own best-effort ROLLBACK in the read-only transaction backstop — silently queues behind the abandoned statement and only runs once the real (still in-flight) server response for it eventually arrives. This is also why the issue's repro saw DBHub return at ~8s for a 3s query_timeout: it was blocked inside that ROLLBACK, waiting out SLEEP(8).

MariaDB is not affected the same way: src/connectors/mariadb/index.ts maps queryTimeout to the server session variable max_statement_time, which is real server-side enforcement.

Changes

• src/utils/readonly-transaction.ts: added isClientSideTimeout() and skip the doomed ROLLBACK for that error class instead of hanging behind it.
• src/connectors/mysql/index.ts: on PROTOCOL_SEQUENCE_TIMEOUT, best-effort issue KILL QUERY <threadId> over a separate pooled connection (the original connection's queue can't be used for anything else), then conn.destroy() the poisoned connection instead of conn.release()-ing it back to the pool, per mysql2's own documented contract for timed-out connections.

Test plan

• Added a unit test covering the timeout path: rollback skipped, KILL QUERY sent on a fresh connection, original connection destroyed (not released).
• Full unit + integration suite passes (pnpm test, includes MySQL/MariaDB Testcontainers): 48 files / 1252 tests.
• tsc --noEmit shows no new errors.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR fixes MySQL query timeouts so they don’t leave server-side statements running and don’t return a poisoned pooled connection that can hang subsequent callers. It adds explicit handling for mysql2’s client-side-only timeout behavior by skipping rollback (which would otherwise block) and attempting to terminate the server-side query, then discarding the bad connection.

Changes:

• Add isClientSideTimeout() helper and skip ROLLBACK for mysql2 timeout errors in the read-only transaction backstop.
• In the MySQL connector, detect PROTOCOL_SEQUENCE_TIMEOUT, attempt KILL QUERY <threadId> via a separate pooled connection, and destroy() the timed-out connection instead of releasing it.
• Add a unit test covering the timeout path: rollback skipped, kill issued on a fresh connection, and the original connection destroyed.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
src/utils/readonly-transaction.ts	Skips rollback for mysql2 client-side timeouts to avoid post-timeout hangs on the same connection.
src/connectors/mysql/index.ts	Attempts server-side cancellation and destroys poisoned connections on mysql2 timeouts.
src/connectors/tests/readonly-transaction-strategy.test.ts	Adds unit coverage for the timeout cleanup behavior (skip rollback, kill query, destroy connection).

Suppressed comments (1)

src/connectors/mysql/index.ts:751

• KILL QUERY is part of the timeout cleanup path; it should be time-bounded as well so it can’t stall indefinitely if the server is unhealthy. Consider using mysql2 QueryOptions with a small timeout (independent of the user query timeout).

      killer = await this.pool.getConnection();
      await killer.query(`KILL QUERY ${threadId}`);
    } catch {

[tianzhou]

Addressed: the KILL QUERY cleanup call now carries its own short, fixed timeout (independent of the user's query_timeout), and if that kill itself times out client-side, the killer connection is destroyed rather than released — it's subject to the same stuck-queue hazard as the original connection. See 5ab2b8b.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

Suppressed comments (2)

src/connectors/mysql/index.ts:760

• In strict TS mode, let killer; is an implicit-any compile error. Also, killQuery is described as "bounded" by a short timeout, but only the KILL QUERY call is timed out — pool.getConnection() can still wait indefinitely under pool exhaustion, causing the timeout path to hang again. Consider bounding the connection acquisition (and ensuring any late-acquired connection is immediately released) before issuing KILL QUERY.

    if (!this.pool) return;
    let killer;
    let killerPoisoned = false;
    try {
      killer = await this.pool.getConnection();
      await killer.query({ sql: `KILL QUERY ${threadId}`, timeout: MySQLConnector.KILL_QUERY_TIMEOUT_MS });

src/connectors/mysql/index.ts:727

• This adds a mocked unit test for the timeout path, but there’s still no integration-level regression test proving the end-to-end behavior against a real MySQL server (e.g., query_timeout triggers promptly and a subsequent unrelated query is not blocked, or the timed-out statement disappears from PROCESSLIST). Given this fixes a production incident (#384), adding an integration test would better protect against regressions in mysql2/pool behavior.

    } catch (error) {
      if (isClientSideTimeout(error)) {
        // mysql2's `timeout` option only aborts client-side: the statement
        // keeps running on the server and this connection's command queue
        // still thinks that statement is in flight (see isClientSideTimeout).
        // Best-effort kill the server-side statement over a fresh connection
        // so the timeout actually frees whatever the query was holding.
        isConnectionPoisoned = true;
        await this.killQuery(threadId);
      }