Laravel Mariadb Laravel Package

Product Decisions This Supports

• Whether MariaDB is a supported deployment target. For products shipped to self-hosted, on-prem, or budget-hosting customers (where MariaDB is frequently the preinstalled "MySQL"), this package decides whether JSON-backed features work or hard-fail. That's a packaging and market-segmentation call, not an engineering detail.
• Build vs. buy on a narrow gap. The alternatives are (a) hand-rolling a grammar override in our own service provider, (b) requiring MySQL 8 on every deployment, or (c) branching SQL per engine. Adopting a ~1-file dependency transfers maintenance of a well-bounded grammar difference.
• Feature scoping / tiering. Any feature leaning on whereJsonContains, JSON path selects, or JSON length queries can be kept at parity across MySQL and MariaDB instead of being silently marked "MySQL 8+ only."
• Roadmap: database migration paths. De-risks a move to MariaDB (licensing, hosting cost, customer environment) or a dual-engine support commitment without rewriting Eloquent queries or degrading JSON functionality.
• Use cases: multi-tenant SaaS with per-customer database choice; Laravel apps sold into hosting environments where the engine isn't ours to pick; internal tools on managed MariaDB; legacy lift-and-shift where MySQL 8 isn't available.

When to Consider This Package

Adopt when:

• We run Laravel on MariaDB (not MySQL 5.7/8) and our code uses Laravel's JSON query-builder API.
• We must support both MySQL and MariaDB from one codebase and can't fork SQL per environment.
• We distribute to customers whose database engine we don't control.
• The breakage is confined to JSON selects/where clauses — this patches grammar, not the driver.

Look elsewhere / skip when:

• We're MySQL 8+ only — Laravel handles it natively and this is dead weight.
• We're on PostgreSQL — different problem, not this package.
• JSON usage is trivial (column stored, decoded in PHP) — app-side decoding avoids a dependency.
• We need guaranteed maintained support. At ~96 stars with a single maintainer, verify the Laravel 10/11/12 × MariaDB 10.6/11.x matrix ourselves; if we can't pin a tested combination, budget for owning the override.
• Procurement/security review treats an unreviewed third-party patch to SQL generation as a blocker.
• A MySQL 8 migration lands within ~6 months — the dependency won't amortize.

Mitigations regardless: pin the version, add a real MariaDB service to CI (not SQLite), smoke-test each JSON operator we rely on, and keep the patch small enough to vendor if it's abandoned.

How to Pitch It (Stakeholders)

Executives: A small, targeted dependency that lets us support MariaDB — a large share of self-hosted and budget-hosting environments — without maintaining a fork of our app or forcing customers onto MySQL 8. Cost is one Composer package; the risk is single-maintainer open source, which we contain by pinning versions and keeping the patch vendor-able if needed.

Engineering: Laravel's MySQL grammar emits JSON SQL that doesn't behave correctly against MariaDB. This package supplies the MariaDB-specific grammar so whereJsonContains and JSON path selects work unchanged. It's a grammar patch, not a driver change — review surface is SQL generation only. Actions: pin the version, add a MariaDB container to the CI matrix, add one smoke test per JSON operator in use, and confirm supported Laravel/MariaDB version pairs before committing.