README

A MatrixOne database driver for Laravel. Use MatrixOne as a drop-in Laravel database: Eloquent, Query Builder, Schema Builder, migrations, transactions and Laravel's own testing traits — plus vector search.

Features

matrixone driver built on Laravel's MySQL stack — read/write splitting, reconnects and lazy connections work like a built-in driver
Eloquent & Query Builder — relationships, eager loading, soft deletes, upserts, JSON columns, full-text search, pagination
Schema Builder & migrations — migrate, migrate:fresh, db:wipe, db:show and schema introspection adapted to MatrixOne's catalog
Cache, queue and session — Laravel's database cache, lock, queue (batches, failed jobs) and session drivers work
Real transactions — RefreshDatabase, DatabaseTransactions and DatabaseTruncation work unchanged
Vector search — vecf32 / vecf64 columns, IVF-Flat and HNSW indexes, an AsVector cast and nearest-neighbour queries
MatrixOne-aware — works around MatrixOne quirks and fails clearly on unsupported features
PHP 8.2+, Laravel 12 and 13, MatrixOne 4.2+

Installation

composer require vuthaihoc/laravel-matrixone

Add a connection to config/database.php:

'connections' => [
    'matrixone' => [
        'driver' => 'matrixone',
        'host' => env('DB_HOST', '127.0.0.1'),
        'port' => env('DB_PORT', 6001),
        'database' => env('DB_DATABASE', 'laravel'),
        'username' => env('DB_USERNAME', 'root'),
        'password' => env('DB_PASSWORD', '111'),
        'charset' => 'utf8mb4',
        'collation' => 'utf8mb4_unicode_ci',
        'prefix' => '',
        'strict' => true,
    ],
],

Set DB_CONNECTION=matrixone to make it the default connection. See Installation for every option.

Application users without admin rights

The driver works with an ordinary MatrixOne user that owns one database through a role:

create database `app_db`;
create role app_rw;
grant all on database `app_db` to app_rw;
grant all on table `app_db`.* to app_rw;
create user app identified by '...' default role app_rw;

MatrixOne denies such a user two things Laravel's MySQL driver relies on, so the driver avoids them:

use app_db fails with "do not have privilege to execute the statement", even when the role owns the database. Laravel's MySQL connector runs it after every connect (use_db_after_connecting), and because PDO connects lazily the error shows up on the application's first query, typically the information_schema.tables lookup of migrate. The DSN already selects the database, so the matrixone driver no longer runs use unless 'use_db_after_connecting' => true is set. Applications that added 'use_db_after_connecting' => false as a workaround can remove it.
System catalogs: mo_catalog.mo_foreign_keys and information_schema.key_column_usage are off limits, which broke Schema::getForeignKeys() (and tools built on it, such as db-portable:copy). Foreign keys are now read from SHOW CREATE TABLE, which only needs a privilege on the table itself. This was chosen over granting select on mo_catalog.mo_foreign_keys (which exposes the foreign key metadata of every database in the account) and over catching the error (which would silently hide foreign keys). SHOW CREATE TABLE also keeps the column order of composite keys and reports set null / no action the way Laravel expects; on MatrixOne 4.2.6 its output matched the catalog for every table checked.

Running MatrixOne

Ready-to-use Docker setups live in docker/:

# Standalone, data on local disk (./mo-data)
cd docker/standalone && docker compose up -d

# Standalone, table data on S3 / MinIO: edit docker/s3/etc/*.toml first
cd docker/s3 && docker compose up -d

Connect on 127.0.0.1:6001 as root / 111. See Running MatrixOne with Docker. For clusters, Kubernetes and other deployments, see the MatrixOne documentation.

Quick start

// Migrations use Laravel's Blueprint; the driver adds vector macros.
use Illuminate\Database\Schema\Blueprint;

Schema::create('documents', function (Blueprint $table) {
    $table->id();
    $table->string('title');
    $table->vector('embedding', 3);
    $table->vectorIndex('embedding');
    $table->timestamps();
});

// Models are plain Eloquent models.
use Illuminate\Database\Eloquent\Model;
use MatrixOne\Eloquent\Casts\AsVector;

class Document extends Model
{
    protected $guarded = [];

    protected function casts(): array
    {
        return ['embedding' => AsVector::class];
    }
}

Document::create(['title' => 'MatrixOne', 'embedding' => [0.1, 0.2, 0.3]]);

// The 5 nearest documents by cosine distance.
Document::nearestTo('embedding', [0.1, 0.2, 0.25], 5)->get();

// Laravel's own vector methods work too.
Document::whereVectorSimilarTo('embedding', [0.1, 0.2, 0.25], minSimilarity: 0.8)->get();

AI assistants (Laravel Boost)

The package ships Laravel Boost resources, picked up automatically when you run php artisan boost:install (or boost:update):

a guideline (resources/boost/guidelines/core.blade.php) with the rules an AI agent must follow on MatrixOne, such as no FULLTEXT index on a table with foreign keys, case-sensitive = and no JSON defaults;
a matrixone-development skill (resources/boost/skills/matrixone-development/SKILL.md) covering schema design, queries, full-text, vectors, Scout, session variables and known server bugs.

See AI Assistants for installation, updates, customization and use without Boost.

Documentation

Page	Content
Installation	Requirements and configuration
Docker	Standalone and S3-backed MatrixOne servers, extra compute nodes
Query Builder	Behaviour differences, JSON, full-text and vector queries
Eloquent	Models, the `AsVector` cast, transactions
Full-text Search	Parsers, relevance, session variables, FULLTEXT2
Storage and Flushing	Flushing tables to object storage (S3) on a schedule, checkpoints
Monitoring	Statement history, slow queries, execution plans, table statistics
Analytics	Window functions, time windows, sampling, snapshots, time travel, CLUSTER BY
Integrations	Laravel Scout (in-table and separate index), Pulse and Telescope
Schema	Column types, indexes, vector indexes, introspection
Testing	Laravel testing traits on MatrixOne
AI Assistants	Laravel Boost guideline and `matrixone-development` skill
Compatibility	Every MatrixOne difference the driver handles or rejects
Companion Packages	laravel-db-portable and the CockroachDB driver

Testing

(cd docker/standalone && docker compose up -d)   # MatrixOne 4.2.6 on 127.0.0.1:6001 (root / 111)
composer test               # the database driver (Unit + Feature)
composer test:monitoring    # statement history and slow queries (slow, separate suite)

See Testing for every suite.

TODO

Towards full parity with Laravel's MySQL and PostgreSQL drivers:

Case-insensitive string equality helpers (MatrixOne ignores _ci collations for = and unique indexes)
php artisan db support for the matrixone driver
schema:dump through MatrixOne's mo-dump
Verified reconnects after lost connections and server restarts
Tests for UUID/ULID keys, time zones and microsecond timestamps
Verified integration with Scout's database engine, Pulse and Telescope
matrixone-index Scout engine: MatrixOne as a separate search index for models in any database
Snapshot / time-travel helpers
Time windows, sampling and CLUSTER BY
Slow query and statement history helpers (statementLog(), matrixone:slow-queries, tableStats())
Hybrid full-text + vector search helper
Bulk loading with LOAD DATA
Compatibility matrix across MatrixOne 4.2.x releases
Release v1.0.0 on Packagist and publish the docs site
Benchmarks against MySQL

Related packages

vuthaihoc/laravel-db-portable: query builder macros that compile for MatrixOne, MySQL, PostgreSQL/CockroachDB and SQLite, and scan / audit / copy commands for moving an application to MatrixOne.
vuthaihoc/cockroachdb-laravel: the CockroachDB driver used on the other side of such a move.

Credits

Based on laravel-clickhouse.

License

MIT. See LICENSE.

vuthaihoc / laravel-matrixone

Package info

Security

Statistics