MariaDB with Laravel
Assume MariaDB 11.8 (LTS) and Laravel 13 if not explicitly told.
Laravel ships a dedicated MariaDB driver since Laravel 11. It is not the same as the
mysql driver: it has its own connection, connector, query grammar and schema grammar,
and it is the only one that emits MariaDB-specific SQL.
Requirements
- PHP 8.2+ with the
pdo_mysqlextension (php -m | grep pdo_mysql). - No extra Composer package. MariaDB support is part of the framework.
Configuration
.env:
DB_CONNECTION=mariadb
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=laravel
DB_USERNAME=sail
DB_PASSWORD=password
config/database.php — the mariadb connection is identical to the mysql one except
for the driver key:
'mariadb' => [
'driver' => 'mariadb',
'url' => env('DB_URL'),
'host' => env('DB_HOST', '127.0.0.1'),
'port' => env('DB_PORT', '3306'),
'database' => env('DB_DATABASE', 'laravel'),
'username' => env('DB_USERNAME', 'root'),
'password' => env('DB_PASSWORD', ''),
'charset' => env('DB_CHARSET', 'utf8mb4'),
'collation' => env('DB_COLLATION', 'utf8mb4_unicode_ci'),
'prefix' => '',
'prefix_indexes' => true,
'strict' => true,
'engine' => null,
],
A fresh Laravel application already contains this block — only DB_CONNECTION has to be
changed.
Always use the mariadb driver against a MariaDB server
Pointing the mysql driver at a MariaDB server appears to work — basic CRUD and most
migrations run fine — and then fails in specific, hard-to-diagnose places:
| Feature | mariadb driver |
mysql driver on a MariaDB server |
|---|---|---|
| Vector distance queries | supported | RuntimeException: Vector distance queries are only supported by Postgres and MariaDB. |
uuid() column |
native uuid type (MariaDB 10.7+) |
char(36) |
renameColumn() |
the 10.5.2 threshold | the 8.0.3 threshold, so MariaDB 10.4 and older get syntax they reject |
geometry() SRID |
ref_system_id= |
srid=, rejected by MariaDB |
vectorIndex() |
vector index ... M=6 DISTANCE=cosine |
RuntimeException: The database driver in use does not support vector indexes. |
JSON paths (where('data->k')) |
json_value(...) |
json_unquote(json_extract(...)) |
| Lateral joins | explicit "not supported" error | invalid SQL sent to the server |
Check what a connection actually uses:
DB::connection()->getDriverName(); // "mariadb"
DB::connection()->getServerVersion(); // "11.8.2-MariaDB"
DB::connection()->isMaria(); // true
Version support
- Laravel's own CI runs the integration suite against MariaDB 10.11, 11.8 LTS and 12.3 LTS.
- Vector columns and vector distance queries require MariaDB 11.7+ (11.8 LTS recommended;
VECTORwas a preview in 11.7 and became GA in 11.8). - A multi-table
DELETE ... ORDER BY ... LIMITis accepted from 11.8.1 (MDEV-30469); it raises an error on earlier versions and on MySQL. Gate any code that relies on it on the server version rather than on the driver name.
Docker / Laravel Sail
services:
mariadb:
image: 'mariadb:11.8'
environment:
MARIADB_ROOT_PASSWORD: '${DB_PASSWORD}'
MARIADB_DATABASE: '${DB_DATABASE}'
MARIADB_USER: '${DB_USERNAME}'
MARIADB_PASSWORD: '${DB_PASSWORD}'
ports:
- '${FORWARD_DB_PORT:-3306}:3306'
volumes:
- 'sail-mariadb:/var/lib/mysql'
healthcheck:
test: ['CMD', 'healthcheck.sh', '--connect', '--innodb_initialized']
sail up then php artisan migrate. Use mariadb:11.8 or later — the mariadb:10 image
cannot run vector workloads.
Related skills
mariadb-laravel-vector— vector columns, indexes and similarity search in Laravel.