Laravel Geoscope Laravel Package

Getting Started

This release (2.0.2) is a patch that adds MariaDB support, so the package is now usable against a MariaDB server in addition to its existing MySQL support. Start by confirming compatibility on both axes: the package version (^2.0.2) and your database stack.

1. Upgrade with composer require vendor/package:^2.0.2 and commit the lockfile — the change is additive, so no migration steps should be required, but the lockfile bump is what makes the new branch support deterministic across environments.
2. Check your Laravel version. Laravel 11+ ships a first-class mariadb driver; on Laravel 10 and below you must keep 'driver' => 'mysql' in config/database.php and let the package's grammar/feature detection handle the difference. Do not set driver => mariadb on a framework that doesn't recognise it — it will fail at connection resolution, not at query time.
3. Read the changelog for the whole 2.0.x line, not just 2.0.2. Patch releases like this often carry the grammar tweaks that make the new branch work; knowing what landed in 2.0.0 and 2.0.1 tells you what "supported" actually covers.
4. Look first at the package's service provider (for config/grammar bindings) and its tests/ directory. If there is a driver matrix or a phpunit.xml with a DB_CONNECTION env, that is the fastest map of what the maintainer actually verified.

First use case: point an existing local project at MariaDB without changing application code. Spin up mariadb:10.11 (the current LTS), reuse your existing env keys, and run your test suite unchanged. If everything passes, the 2.0.2 support is doing its job; if something fails, you've isolated the diff to the database layer before touching production.

Implementation Patterns

Keep both connections defined side by side. Add a mariadb connection block to config/database.php that mirrors your mysql block but reads from DB_HOST/DB_DATABASE as usual. This lets you switch drivers per-environment (SQLite in unit tests, MariaDB in CI, MySQL or MariaDB in production) without conditional config logic scattered through the app.

Prefer capability detection over version sniffing. The single biggest source of driver bugs is code that branches on a raw version string. Wrap the checks you actually need — JSON function availability, RETURNING support, window functions, CTE support — in a small class of your own, and have that class ask the connection once rather than parsing versions at every call site. If the package exposes a grammar or feature-flag object, delegate to it instead of duplicating the logic.

Run a real driver matrix in CI. A matrix that only exercises MySQL will not catch MariaDB regressions, and vice versa. The minimum useful set:

services:
  mariadb:
    image: mariadb:10.11
    env:
      MARIADB_ROOT_PASSWORD: root
      MARIADB_DATABASE: testing
    ports: ['3306:3306']
    options: --health-cmd="healthcheck.sh --connect --innodb_initialized"

Pair it with a mysql:8.0 job and a sqlite job if you support all three. Use Pest datasets or a PHPUnit data provider to run the same test class against each connection name rather than duplicating tests.

Migrate before you assert. Any test that touches schema should run RefreshDatabase or migrate:fresh against the MariaDB connection at least once in CI. Grammar-level differences rarely show up in SELECTs; they show up in ALTER TABLE, index creation, and column type mapping.

Isolate the upgrade. Bump to 2.0.2 on a branch, run the full suite against both MySQL and MariaDB, and only then merge. Because this is a patch, the risk profile is low — but "adds support for X" occasionally means "changes the default driver assumption," so diff config/ after the update with php artisan vendor:publish --tag=... --force in a scratch copy to see whether anything shipped new.

Gotchas and Tips

MariaDB version strings will break naive parsers. 10.11.6-MariaDB and 11.4.2-MariaDB have higher major numbers than MySQL 8.0, so any code doing version_compare($version, '8.0', '>=') to gate MySQL 8 features will silently take the wrong branch. Use getDriverName() first, version second.

The mariadb driver name is framework-version dependent. Laravel 11 introduced it as a distinct driver; earlier versions report MariaDB connections as mysql. Code that checks === 'mariadb' will behave differently across your supported Laravel range. Normalise this once, early, in a helper or a base test case.

JSON is not JSON on MariaDB. JSON columns are LONGTEXT with a CHECK (json_valid(...)) constraint. Eloquent's array/json casts work fine, but JSON_TABLE, the ->> operator, and JSON_OVERLAPS availability varies sharply by version, and json_validate() does not exist. If your app relies on server-side JSON querying, verify against your exact MariaDB minor, not against MySQL docs.

Collation and index-length defaults differ across MariaDB versions. MariaDB 10.10+ changed the default collation, and older versions hit the 767-byte index prefix limit that MySQL 8 users never see. Symptom: migrations that pass on MySQL throw Specified key was too long on MariaDB. Fix by setting Schema::defaultStringLength(191) or by explicitly declaring utf8mb4 charset and a compatible collation in the connection config.

INSERT ... RETURNING and DELETE ... RETURNING exist on MariaDB 10.5+ but not on MySQL. If the package surfaces them, guard their use. Conversely, do not assume ON DUPLICATE KEY UPDATE returns generated IDs the same way across both engines — re-query when you need the ID.

sql_mode is not identical. Strict mode is on by default on recent MariaDB, but the full set of flags and their semantics differ from MySQL 8. Code that relies on implicit defaults, zero-dates, or silent truncation will behave differently. Pin sql_mode explicitly in config/database.php if your app depends on it.

Debugging driver-specific behaviour: log the actual SQL and the connection driver name together (DB::listen(fn ($q) => logger()->debug($q->sql, ['connection' => $q->connectionName]))), and compare DDL with SHOW CREATE TABLE on both engines. Differences in generated DDL are the fastest signal that a grammar path diverged.

Extension points: if the package binds a grammar or connection resolver in its service provider, you can override it by re-binding after the package registers — either in AppServiceProvider::boot() or via DB::connection()->setQueryGrammar(...). Check the provider's register() order before doing this; re-binding before the package's own binding will simply be overwritten.

Pin your MariaDB image tag. mariadb:latest moves; mariadb:10.11 and mariadb:11.4 are LTS. Test against both LTS lines plus whichever version production runs, and treat a floating tag as a source of unexplained CI failures.