Add wpdb fallback for wp db query, wp db import, wp db drop, and wp db reset when mysql/mariadb binary is unavailable

[Copilot]

Several wp db commands currently require the mysql/mariadb CLI binary, causing failures with drop-in database engines (HyperDB, custom drivers) or environments where the binary simply isn't installed. This PR adds automatic fallback to WordPress's $wpdb for all relevant commands.

Changes

src/DB_Command.php

• is_mysql_binary_available() — probes for the mysql/mariadb binary via /usr/bin/env <binary> --version; result is statically cached
• maybe_load_wpdb() — loads the minimal WordPress files needed for $wpdb (load.php, compat.php, plugin.php, functions.php, class-wpdb.php), includes any wp-content/db.php drop-in (HyperDB et al.), and falls back to creating a plain wpdb instance with wp-config.php credentials + $table_prefix
• run_query() — now checks binary availability at the top and, when absent, routes through maybe_load_wpdb() + $wpdb->query() instead of invoking the mysql CLI. This covers drop and reset.
• query() — after the existing SQLite branch, checks binary availability and routes to the new wpdb path when absent via wpdb_query()
• wpdb_query() — executes arbitrary SQL via $wpdb; mirrors the mysql-path behaviour (row-count reporting for DML, formatted tabular output for SELECT, --skip-column-names support)
• import() — when the mysql binary is unavailable, reads the SQL file (or STDIN) and delegates to wpdb_import()
• wpdb_import() — executes a SQL dump through $wpdb statement-by-statement, applying the same autocommit=0 / unique_checks=0 / foreign_key_checks=0 … COMMIT optimizations as the mysql path (unless --skip-optimization is passed)
• split_sql_statements() — splits a SQL string into individual statements using a state-machine parser that correctly handles single-quoted strings, double-quoted strings, -- line comments, and /* */ block comments

features/db-query.feature

Added a @require-mysql-or-mariadb scenario that shadows the real binary with a fake exit 127 script via PATH prepending, then asserts the query succeeds and the debug message confirms the fallback was taken.

features/db.feature

Added @require-mysql-or-mariadb scenarios for wp db drop and wp db reset that shadow the binary with a fake exit 127 script and assert each command succeeds via the wpdb path (verified via the Query via wpdb: debug line).

features/db-import.feature

Added a @require-mysql-or-mariadb scenario that exports a real SQL dump first, then shadows the binary and re-imports it, asserting success and the MySQL/MariaDB binary not available, falling back to wpdb for import. debug message.

Note: wp db create is not covered by the wpdb fallback because wpdb requires the target database to already exist in order to establish a connection — a from-scratch create (no DB yet) cannot be handled via vanilla wpdb.

Summary by CodeRabbit

• New Features

  • Database commands now automatically fall back to WordPress database connectivity when MySQL or MariaDB client tools are unavailable.
  • Added fallback support for database queries, SQL imports, database drops, and resets.
  • Query results and command output remain compatible with existing command-line formatting.

• Bug Fixes

  • Database operations can now complete successfully in environments without installed MySQL/MariaDB binaries.
  • Added clearer diagnostic warnings when fallback execution is used.

[codecov]

Codecov Report

❌ Patch coverage is 78.57143% with 39 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/DB_Command.php	78.57%	39 Missing ⚠️

📢 Thoughts on this report? Let us know!

[Copilot]

Pull request overview

This PR adds a fallback execution path for several wp db subcommands when the mysql/mariadb client binary is not available, and extends Behat coverage to validate the fallback behavior by shadowing the client binaries via PATH.

Changes:

• Added mysql/mariadb binary availability detection and routed wp db query / wp db import (and DDL via run_query()) through a PHP-based fallback when unavailable.
• Implemented SQL execution/import helpers (including SQL dump statement splitting) for the fallback path.
• Added Behat scenarios that simulate missing client binaries and assert fallback success + debug output.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 5 comments.

File	Description
src/DB_Command.php	Adds mysql binary probing, mysqli-based fallback execution/import, and a SQL statement splitter for imports.
features/db.feature	Adds scenarios verifying wp db drop and wp db reset succeed when mysql/mariadb binaries are shadowed.
features/db-query.feature	Adds scenario verifying wp db query succeeds and logs fallback when mysql/mariadb binaries are shadowed.
features/db-import.feature	Adds scenario verifying wp db import succeeds and logs fallback when mysql/mariadb binaries are shadowed.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 97ae9620-fa12-494d-9f24-e6d3decb32c9

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• ✅ Review completed - (🔄 Check again to review again)

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch copilot/fix-wp-db-query-fallback

---

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

[coderabbitai]

Actionable comments posted: 3

🧹 Nitpick comments (3)

src/DB_Command.php (1)

1977-1997: 🚀 Performance & Scalability | 🔵 Trivial | ⚡ Quick win

Uses a fresh connection per DDL call — fine for single calls, costly in clean()'s loop.

run_query() now routes every run_query() caller through this method when the binary is unavailable, including clean(), which calls run_query() once per table (Lines 235-244). Each call opens and closes a brand-new mysqli connection just to run one DROP TABLE. For large installs with many tables this multiplies connection overhead unnecessarily.

♻️ Suggested direction

Accept an optional existing mysqli connection (or expose a connection-reuse variant) so callers that issue many DDL statements in a loop (like clean()) can reuse a single connection instead of opening one per statement.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/DB_Command.php` around lines 1977 - 1997, Update run_query_via_mysqli()
to accept an optional existing mysqli connection, creating and closing its own
connection only when one is not provided. Modify clean() to obtain one reusable
connection before its table-drop loop and pass it to each run_query_via_mysqli()
call, then close it after the loop while preserving existing error handling.

features/db-query.feature (1)

158-183: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Scenario correctly matches the fallback's debug message; consider adding SQL-mode-compat coverage.

This scenario is well-formed and the previously requested env PATH=... fix is already applied. Given the critical SQL-mode-compatibility gap identified in wpdb_query()/wpdb_import() (src/DB_Command.php), consider adding a fallback scenario analogous to "wp db query adapts the SQL mode by default without a separate mode probe" (Lines 100-113) but using the fake-bin technique, so a fix to that gap is actually exercised by CI.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@features/db-query.feature` around lines 158 - 183, Add a fake-bin fallback
scenario in features/db-query.feature that verifies wp db query adapts SQL mode
by default without a separate mode probe, using the same PATH override and
unavailable mysql/mariadb binaries as the current scenario. Ensure the
assertions exercise the compatibility behavior implemented by
DB_Command::wpdb_query() or DB_Command::wpdb_import(), including the expected
query result and debug output.

features/db-import.feature (1)

72-99: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Scenario structure is correct but doesn't reproduce the known regression.

This test imports a plain export on what is likely a lenient-SQL-mode CI database, so it wouldn't fail even with the missing SQL-mode-compat statement in wpdb_import() (see src/DB_Command.php). Consider mirroring "wp db import loads a dump containing legacy zero-date values" (Lines 323-344) but through the fake-bin/mysqli fallback path, since that's the exact scenario that previously surfaced "Invalid default value for 'comment_date'" per the PR history.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@features/db-import.feature` around lines 72 - 99, The fallback scenario
should import a dump containing legacy zero-date values so it exercises the
SQL-mode compatibility logic in DB_Command::wpdb_import(), rather than importing
a plain export. Adapt the existing fake-bin/mysql and fake-bin/mariadb
unavailable setup to use the zero-date dump content and retain assertions for
successful import and the fallback warning.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/DB_Command.php`:
- Around line 2593-2629: Apply get_sql_mode_compat_statement( $assoc_args ) to
the fallback connection before executing SQL in both src/DB_Command.php lines
2593-2629 within wpdb_import() and lines 2535-2583 within wpdb_query(); each
site requires the same compatibility statement before the split statements or
query runs.
- Around line 2008-2013: Update the run_query() fallback around
is_mysql_binary_available() so database creation does not route through
run_query_via_mysqli() without a selected database. Exclude the create()
operation from this fallback, preserving the existing mysqli behavior for other
queries, or explicitly align the command documentation and design with
supporting create() through that path.
- Around line 2481-2524: Update get_db_connection() to use the command’s
effective CLI database username and password values, including --dbuser and
--dbpass overrides, instead of always reading DB_USER and DB_PASSWORD. Handle
mysqli connection exceptions so failures reach the existing WP_CLI::error()
path, and ensure fallback query operations similarly tolerate or catch mysqli
exceptions before relying on connect_errno/query checks.

---

Nitpick comments:
In `@features/db-import.feature`:
- Around line 72-99: The fallback scenario should import a dump containing
legacy zero-date values so it exercises the SQL-mode compatibility logic in
DB_Command::wpdb_import(), rather than importing a plain export. Adapt the
existing fake-bin/mysql and fake-bin/mariadb unavailable setup to use the
zero-date dump content and retain assertions for successful import and the
fallback warning.

In `@features/db-query.feature`:
- Around line 158-183: Add a fake-bin fallback scenario in
features/db-query.feature that verifies wp db query adapts SQL mode by default
without a separate mode probe, using the same PATH override and unavailable
mysql/mariadb binaries as the current scenario. Ensure the assertions exercise
the compatibility behavior implemented by DB_Command::wpdb_query() or
DB_Command::wpdb_import(), including the expected query result and debug output.

In `@src/DB_Command.php`:
- Around line 1977-1997: Update run_query_via_mysqli() to accept an optional
existing mysqli connection, creating and closing its own connection only when
one is not provided. Modify clean() to obtain one reusable connection before its
table-drop loop and pass it to each run_query_via_mysqli() call, then close it
after the loop while preserving existing error handling.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 147dfdef-c9e6-4d69-9dda-8223e5fcbc7f

📥 Commits

Reviewing files that changed from the base of the PR and between 4f7635d and 6051f7f.

📒 Files selected for processing (4)

• features/db-import.feature
• features/db-query.feature
• features/db.feature
• src/DB_Command.php

[coderabbitai]

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

# Inspect relevant methods in src/DB_Command.php
grep -nE 'function (create|run_query|run_query_via_mysqli|get_db_connection|is_mysql_binary_available)' -n src/DB_Command.php

# Show the relevant sections with line numbers
sed -n '1,180p' src/DB_Command.php
echo '---'
sed -n '1960,2060p' src/DB_Command.php
echo '---'
sed -n '2060,2145p' src/DB_Command.php

Repository: wp-cli/db-command

Length of output: 11488

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

# Inspect the connection helper and surrounding logic.
sed -n '2470,2575p' src/DB_Command.php

# Show any references to create() / unsupported / fallback in this file.
grep -nE 'unsupported|fallback|mysqli|CREATE DATABASE|run_query_via_mysqli|maybe_load_sqlite_dropin' src/DB_Command.php

Repository: wp-cli/db-command

Length of output: 5535

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

sed -n '2470,2575p' src/DB_Command.php
echo '---'
grep -nE 'unsupported|fallback|mysqli|CREATE DATABASE|run_query_via_mysqli|maybe_load_sqlite_dropin' src/DB_Command.php

Repository: wp-cli/db-command

Length of output: 5539

---

wp db create still goes through the mysqli fallback. create() calls run_query(), and the no-binary path uses run_query_via_mysqli() with no selected database, so CREATE DATABASE will succeed there. Either exclude create() from this fallback or update the command docs/design to say it’s supported.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/DB_Command.php` around lines 2008 - 2013, Update the run_query() fallback
around is_mysql_binary_available() so database creation does not route through
run_query_via_mysqli() without a selected database. Exclude the create()
operation from this fallback, preserving the existing mysqli behavior for other
queries, or explicitly align the command documentation and design with
supporting create() through that path.

[coderabbitai]

🩺 Stability & Availability | 🔴 Critical | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf 'Repo root: '; pwd
printf '\nRelevant PHP files around DB_Command:\n'
git ls-files 'src/DB_Command.php' 'composer.json' 'phpcs.xml.dist' 'README*' 'docs/**' 'bin/**' | sed 's#^`#-` #'

printf '\nSearch for PHP version requirements:\n'
rg -n --hidden -S "PHP ?8\.1|minimum PHP|PHP_VERSION|Requires PHP|php >=|php:" composer.json README* docs src bin .github 2>/dev/null || true

printf '\nSearch for mysqli_report / get_db_connection / dbuser usage:\n'
rg -n -S "mysqli_report|get_db_connection\(|dbuser|dbpass|DB_USER|DB_PASSWORD" src/DB_Command.php src 2>/dev/null || true

Repository: wp-cli/db-command

Length of output: 12267

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf 'src/DB_Command.php outline:\n'
ast-grep outline src/DB_Command.php --view expanded | sed -n '1,260p'

printf '\nTargeted slices around relevant methods:\n'
sed -n '2400,2605p' src/DB_Command.php | cat -n

Repository: wp-cli/db-command

Length of output: 11393

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf 'composer.json (version-related keys):\n'
if [ -f composer.json ]; then
  python3 - <<'PY'
import json
from pathlib import Path
p = Path("composer.json")
data = json.loads(p.read_text())
for k in ["require", "require-dev", "config", "scripts"]:
    if k in data:
        print(f"\n[{k}]")
        print(data[k])
PY
fi

printf '\nphpcs.xml.dist snippets:\n'
if [ -f phpcs.xml.dist ]; then
  rg -n -S "php_version|PHP|testVersion|runtime" phpcs.xml.dist || true
fi

Repository: wp-cli/db-command

Length of output: 1340

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf 'README and package metadata around requirements/support:\n'
rg -n -S "PHP 7|PHP 8|minimum supported|requires PHP|WP-CLI|require-php|testVersion|7\.2-|8\.1|mysqli" README.md composer.json phpcs.xml.dist src 2>/dev/null || true

printf '\nREADME top section:\n'
sed -n '1,120p' README.md | cat -n

Repository: wp-cli/db-command

Length of output: 5985

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf 'README and package metadata around requirements/support:\n'
rg -n -S "PHP 7|PHP 8|minimum supported|requires PHP|WP-CLI|require-php|testVersion|7\\.2-|8\\.1|mysqli" README.md composer.json phpcs.xml.dist src 2>/dev/null || true

printf '\nREADME top section:\n'
sed -n '1,120p' README.md | cat -n

Repository: wp-cli/db-command

Length of output: 5985

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

sed -n '1968,2615p' src/DB_Command.php | cat -n | sed -n '1,280p'

Repository: wp-cli/db-command

Length of output: 11990

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

python3 - <<'PY'
from pathlib import Path
p = Path("src/DB_Command.php")
lines = p.read_text().splitlines()
for start,end in [(1978,2028),(2528,2610)]:
    print(f"\n--- {start}-{end} ---")
    for i in range(start-1, min(end, len(lines))):
        print(f"{i+1:5d}: {lines[i]}")
PY

Repository: wp-cli/db-command

Length of output: 5329

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

# Show where the command-level assoc args are consumed for the mysql binary path.
python3 - <<'PY'
from pathlib import Path
lines = Path("src/DB_Command.php").read_text().splitlines()
for start,end in [(470,560),(575,650),(930,1015)]:
    print(f"\n--- {start}-{end} ---")
    for i in range(start-1, min(end, len(lines))):
        print(f"{i+1:5d}: {lines[i]}")
PY

Repository: wp-cli/db-command

Length of output: 11555

---

🌐 Web query:

WP-CLI minimum supported PHP version current release 2025

💡 Result:

As of July 21, 2026, the current version of WP-CLI is 2.12.0 [1][2]. The official minimum supported PHP version for WP-CLI is PHP 7.2.24 or later [2][3]. While WP-CLI v2.12.0 maintained compatibility with older PHP versions (including 5.6) through various workarounds [1], official documentation confirms the current requirement as PHP 7.2.24+ [3][4]. Developers have noted that future major releases (such as the planned 3.0.0) intend to formalize this 7.2.24+ requirement to remove legacy compatibility code [1][5].

Citations:

• 1: https://make.wordpress.org/cli/2025/05/07/wp-cli-v2-12-0-release-notes/
• 2: https://root.packagist.org/packages/wp-cli/wp-cli
• 3: https://make.wordpress.org/cli/handbook/guides/installing/?output_format=md
• 4: https://github.com/wp-cli/handbook/blob/097b463ba79782edb20860108acad450f35e42fc/guides/installing.md
• 5: WP-CLI 3.0.0 / PHP version requirement tracking issue wp-cli#6026

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf 'Search for any mysqli_report or DB bootstrap tweaks in the repo:\n'
rg -n -S "mysqli_report|MYSQLI_REPORT|wpdb|wp-db.php|database.*bootstrap|bootstrap.*database" . 2>/dev/null || true

Repository: wp-cli/db-command

Length of output: 7349

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

python3 - <<'PY'
from pathlib import Path
for p in Path('.').rglob('*'):
    if p.is_file() and p.suffix in {'.php', '.md', '.json', '.dist', '.txt'}:
        text = p.read_text(errors='ignore')
        if 'mysqli_report' in text or 'MYSQLI_REPORT' in text or 'wp-db.php' in text:
            print(p)
PY

Repository: wp-cli/db-command

Length of output: 502

---

Handle mysqli exceptions and pass CLI credentials through the fallback.

• The package still supports PHP 7.2.24+, so PHP 8.1+ installs can hit mysqli’s default strict mode here and throw before the connect_errno / query() checks run.
• get_db_connection() also still reads DB_USER / DB_PASSWORD directly, so --dbuser / --dbpass are ignored when the binary fallback is used.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/DB_Command.php` around lines 2481 - 2524, Update get_db_connection() to
use the command’s effective CLI database username and password values, including
--dbuser and --dbpass overrides, instead of always reading DB_USER and
DB_PASSWORD. Handle mysqli connection exceptions so failures reach the existing
WP_CLI::error() path, and ensure fallback query operations similarly tolerate or
catch mysqli exceptions before relying on connect_errno/query checks.

[coderabbitai]

🎯 Functional Correctness | 🔴 Critical | 🏗️ Heavy lift

Missing SQL-mode compatibility is one root cause shared by both mysqli fallback executors. Neither wpdb_import() nor wpdb_query() applies get_sql_mode_compat_statement() on the fallback connection, unlike the CLI path's --init-command. This is the specific regression the PR objectives describe ("Invalid default value for 'comment_date'" on WordPress 4.9, and continued failures across versions).

• src/DB_Command.php#L2593-L2629: in wpdb_import(), run $this->get_sql_mode_compat_statement( $assoc_args ) on the connection before executing the split statements.
• src/DB_Command.php#L2535-L2583: in wpdb_query(), run the same compatibility statement on the connection before executing $query.

🧰 Tools

🪛 ast-grep (0.44.1)

[error] 2598-2598: Prevent SQL queries built from unsanitized input
Context: $conn->query( 'SET autocommit = 0' )
Note: [CWE-89] Improper Neutralization of Special Elements used in an SQL Command ('SQL Injection').

(sql-injection-php)

---

[error] 2599-2599: Prevent SQL queries built from unsanitized input
Context: $conn->query( 'SET unique_checks = 0' )
Note: [CWE-89] Improper Neutralization of Special Elements used in an SQL Command ('SQL Injection').

(sql-injection-php)

---

[error] 2600-2600: Prevent SQL queries built from unsanitized input
Context: $conn->query( 'SET foreign_key_checks = 0' )
Note: [CWE-89] Improper Neutralization of Special Elements used in an SQL Command ('SQL Injection').

(sql-injection-php)

---

[error] 2610-2610: Prevent SQL queries built from unsanitized input
Context: $conn->query( $statement )
Note: [CWE-89] Improper Neutralization of Special Elements used in an SQL Command ('SQL Injection').

(sql-injection-php)

---

[error] 2613-2613: Prevent SQL queries built from unsanitized input
Context: $conn->query( 'ROLLBACK' )
Note: [CWE-89] Improper Neutralization of Special Elements used in an SQL Command ('SQL Injection').

(sql-injection-php)

---

[error] 2621-2621: Prevent SQL queries built from unsanitized input
Context: $conn->query( 'COMMIT' )
Note: [CWE-89] Improper Neutralization of Special Elements used in an SQL Command ('SQL Injection').

(sql-injection-php)

---

[error] 2622-2622: Prevent SQL queries built from unsanitized input
Context: $conn->query( 'SET autocommit = 1' )
Note: [CWE-89] Improper Neutralization of Special Elements used in an SQL Command ('SQL Injection').

(sql-injection-php)

---

[error] 2623-2623: Prevent SQL queries built from unsanitized input
Context: $conn->query( 'SET unique_checks = 1' )
Note: [CWE-89] Improper Neutralization of Special Elements used in an SQL Command ('SQL Injection').

(sql-injection-php)

---

[error] 2624-2624: Prevent SQL queries built from unsanitized input
Context: $conn->query( 'SET foreign_key_checks = 1' )
Note: [CWE-89] Improper Neutralization of Special Elements used in an SQL Command ('SQL Injection').

(sql-injection-php)

📍 Affects 1 file

• src/DB_Command.php#L2593-L2629 (this comment)
• src/DB_Command.php#L2535-L2583

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/DB_Command.php` around lines 2593 - 2629, Apply
get_sql_mode_compat_statement( $assoc_args ) to the fallback connection before
executing SQL in both src/DB_Command.php lines 2593-2629 within wpdb_import()
and lines 2535-2583 within wpdb_query(); each site requires the same
compatibility statement before the split statements or query runs.