Detect and surface database driver/server mismatch - #4682
Merged
Conversation
Flarum 2.x treats MariaDB as a distinct driver from MySQL (separate Illuminate connection classes and query grammars). Configuring the 'mysql' driver against a MariaDB server (or vice versa) produces subtle, hard-to-diagnose query bugs that surface as seemingly unrelated reports. Detect the mismatch by comparing the configured driver against the server's reported version, and surface it both in the admin dashboard (as an error banner) and in `php flarum info`, telling the user exactly which driver to set in config.php.
9 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The problem
Since 2.x, Flarum treats MariaDB as a database driver distinct from MySQL. On Illuminate 13 each driver has its own connection class (
MySqlConnectionvsMariaDbConnection) and its own query grammar, so the two are not interchangeable.In practice, a large number of "something isn't working" reports come down to a single misconfiguration: the user has
'driver' => 'mysql'inconfig.phpwhile actually connecting to a MariaDB server (or, less commonly, the reverse). This is extremely easy to do when upgrading from 1.x or following older guides, wheremysqlwas the only relevant option. Because the connection still succeeds, the mismatch is invisible — it only shows up later as subtle, hard-to-diagnose query bugs that look unrelated to the database config.Today nothing tells the admin that their configured driver doesn't match the server they're actually talking to.
What this does
Detects the mismatch and makes it impossible to miss, in the two places admins already look:
'driver' => '…'value to set inconfig.php, with a link to the docs.php flarum info— the database line is flagged inline, plus a trailing error explaining how to fix it (alongside the existing debug-mode notice).How detection works
Only MySQL and MariaDB can be confused for one another, so detection is scoped to those two drivers. A new
ApplicationInfoProvider::identifyDatabaseDriverMismatch()compares the configured driver against the server's reportedversion()string — the sameMariaDBmarker the installer already relies on inConnectToDatabase. It returns the driver that should be configured, ornullwhen everything matches. The lookup reuses the existing 24h cache layer, so there's no per-request query cost.pgsql/sqliteshort-circuit and never hit the database.