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.

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.4 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