Skip to content

fix(sql): detect failed dbDelta queries masked by later ones - #16

Merged
brianvarskonst merged 3 commits into
mainfrom
fix/dbdelta-error-detection
Nov 16, 2026
Merged

brianvarskonst merged 3 commits into
mainfrom
fix/dbdelta-error-detection

Conversation

@brianvarskonst

Copy link
Copy Markdown
Member

Problem

  • Audit Low refactor: split migration cli command #1: WordPressSqlExecutor judged a CREATE TABLE (routed through dbDelta()) only by $wpdb->last_error after the call. For an existing table dbDelta() runs several ALTERs and every wpdb::query() resets last_error, so a failed early ALTER (e.g. a UNIQUE KEY on duplicate data) was masked by a later successful one. The migration was recorded as applied while the index or column was missing.
  • Audit Info Welcome #2: wp migration version --delete was allowed in every environment, while rollback and execute --down are limited to local/development. Unmarking a migration makes the next migrate run its non-idempotent up() again.

Fix

  • During dbDelta(), a temporary query filter checks last_error before each next query (the filter runs before wpdb::flush()), and the executor checks once more after the call. The DESCRIBE probe that dbDelta() runs for new tables is expected to fail and is ignored.
    • The suggested dbDelta($sql, false) === [] convergence check was not used: dbDelta() reports perpetual diffs for valid definitions (int vs int(11) on MariaDB, json vs longtext, bool vs tinyint(1), ...), so working migrations would start to fail.
  • version --delete now uses the existing requireRollbackEnvironment() guard. version --add is unchanged. README, architecture doc and command help are updated.
  • Not changed: the manage_options check that only adopt uses (Info Roadmap feedback #3). Requiring --user on every mutating command would break deploy scripts, so that needs an owner decision.

Tests

  • Unit: WordPressSqlExecutorTest covers a failed ALTER followed by a successful one (fails before the fix) and checks that the DESCRIBE probe for a new table is ignored. The test wpdb/dbDelta() stubs now apply the query filter and can replay several queries.
  • Database: testDbDeltaReportsAFailedAlterFollowedByASuccessfulOne runs against real WordPress and MariaDB 11.8 with a UNIQUE KEY on duplicate data followed by a KEY. Run locally, it fails before the fix and passes after it.
  • MigrationRollbackPolicyTest: version --delete is rejected in production/staging/unknown/empty/DEVELOPMENT without changing state (fails before the fix) and still works in local/development.
  • composer qa (phpcs, PHPStan max, PHPUnit 81 tests) passes, as do composer tests:database (10 tests on MariaDB 11.8) and composer validate --strict.

Release

Patch 1.0.10: CHANGELOG entry and plugin header bump in chore(release): prepare 1.0.10. It also lists the unreleased workflow pin commit.

dbDelta() runs DESCRIBE, SHOW INDEX and several ALTERs for an existing
table, and every wpdb::query() resets last_error. Checking last_error
only after the call missed a failed early ALTER (e.g. a UNIQUE KEY on
duplicate data) when a later ALTER succeeded, so the migration was
recorded as applied while the index was missing.

Inspect last_error before each next query through a temporary 'query'
filter and once more after dbDelta() returns. The DESCRIBE probe that
dbDelta() runs for new tables is expected to fail and is ignored. A
dbDelta($sql, false) convergence check was not used because dbDelta
reports perpetual diffs for valid definitions (e.g. int vs int(11) on
MariaDB, json vs longtext), which would fail working migrations.
Unmarking a migration makes the next `wp migration migrate` run its
up() again, which is not idempotent (e.g. duplicate seed rows). That
is a rollback in effect, yet `version --delete` was allowed in every
environment while `rollback` and `execute --down` are limited to
local/development. Apply the same environment guard; `version --add`
stays available everywhere.
@brianvarskonst
brianvarskonst merged commit 01aa3a8 into main Nov 16, 2026
6 checks passed
@brianvarskonst
brianvarskonst deleted the fix/dbdelta-error-detection branch November 16, 2026 14:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant