Engineering / Field note
WordPress can retry SQL below the query hook
Connection recovery can repeat a database attempt without repeating WordPress’s query filter. That changes what a log entry or once-only guard proves.
An importer can approve a database query once and still leave WordPress free to attempt it again. In the core source examined here, connection recovery happens beneath the query filter. That distinction matters when a migration journal or monitoring dashboard displays one reassuring entry. [1]
This note examines existing behavior, checked on November 19, 2026, in the WordPress 7.1 branch snapshot at commit 572c63d, dated November 18. It establishes a control boundary from public source, rather than a newly disclosed vulnerability, a confirmed duplicate, or a fixed-release recommendation. [2] [7]
Where the second attempt happens
After its first internal dispatch, wpdb::query() checks for an empty database handle or MySQL error 2006. When its connection check succeeds, it calls the internal dispatch method again with the same SQL. That condition does not distinguish a read from a write, and it does not mean every timeout follows this path. [1]
The query filter runs earlier in the method. The recovery branch calls _do_query() directly, without passing through that filter again. Our interpretation is straightforward: a callback attached only to this filter can run once while the surrounding method makes two internal dispatch attempts. [1]
The connection helper also has a loop for reconnecting. Establishing a usable connection and receiving the result of a business operation are different milestones. A connection that is healthy now cannot, by that fact alone, explain what happened before it was recovered. [3]
One journal entry can describe the wrong unit
Consider a hypothetical import tool that records one approved operation whenever its query callback runs. Its journal might accurately say that the application approved the SQL once. If the framework later takes its reconnect branch, that same record would be incomplete as an account of physical attempts. The journal has not necessarily lied; its label promised more than its observation could establish.
This is why an operation, a callback, a driver attempt and a committed result deserve separate names. Collapsing them all into “the query” makes a tidy dashboard, but leaves the person investigating a failure to untangle several different events. A single green tick has a limited vocabulary.
MySQL’s documentation distinguishes a client that could not send its request from one that sent it but received an incomplete answer or none. It also describes platform-dependent connection-loss behavior. These distinctions matter: an error message alone is insufficient grounds for claiming that a particular write committed or that WordPress replayed it. [4]
In the general lost-response case, repeating a creation request can produce an unwanted extra result unless the operation has a suitable idempotent contract. Amazon’s Builders’ Library explains that uncertainty and the role of caller-provided request identifiers. This is broader retry context, not proof that the WordPress error-2006 branch caused a duplicate on any particular system. [5]
For the hypothetical importer, the uncomfortable state is “outcome unknown.” Calling it failed may invite a fresh creation attempt; calling it complete may hide missing work. Preserving that uncertainty makes room for reconciliation against durable records. It also gives an operator an honest explanation for why a workflow paused.
Count evidence at the layer it describes
The inspected WordPress implementation increments its query counter inside _do_query(), and records query timing there when SAVEQUERIES is enabled. That is a different observation point from the earlier query filter. Neither counter nor timing entry, by itself, establishes a committed business outcome. [2]
Our practical reading is that monitoring should describe the event it actually observes. An approval count measures decisions. A dispatch count measures attempts. A durable result identifies the work that exists. Those observations can disagree without any of them being fabricated, provided their meanings remain explicit.
The familiar idempotency question still applies: how does repeated delivery preserve one intended business result? We covered that broader design problem in “When the same automation runs twice.” The additional issue here is placement: retry behavior can live below the application callback that appears to control an attempt. [6]
A policy that allows safe replay and a policy that stops after an uncertain write make different promises. Either needs evidence from the layer that can enforce it. An outer journal cannot establish a no-replay guarantee merely by showing that its own callback ran once. This is a boundary to assess in the actual adapter and version, rather than a reason to install an unreviewed database override.
Connection recovery is useful resilience behavior. The engineering question is what the recovered path is allowed to repeat, and what its evidence can demonstrate afterward. WordPress’s public control flow makes that question concrete: the place where an application notices a query need not be the place where the database attempt happens.
Sources + further reading
Source dates describe the original material. Publication above is the date this Zyel article went live.
- wpdb::query() referenceWordPress · Checked Nov 19, 2026
- Pinned WordPress core database implementationWordPress · Checked Nov 19, 2026
- wpdb::check_connection() referenceWordPress · Checked Nov 19, 2026
- MySQL 8.4 connection-loss error distinctionsOracle MySQL · Checked Nov 19, 2026
- Making retries safe with idempotent APIsAmazon Builders’ Library · Checked Nov 19, 2026
- When the same automation runs twiceZyel · Checked Nov 19, 2026
- WordPress snapshot commit metadataWordPress · Checked Nov 19, 2026
Reader discussion
What would you ask next?
Questions, useful corrections and thoughtful disagreement are welcome. Comments are reviewed before they appear.
No reader comments yet.