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
Query Builder	Behaviour differences, JSON, full-text and vector queries
Eloquent	Models, the `AsVector` cast, transactions
Full-text Search	Parsers, relevance, session variables, FULLTEXT2
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

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

Credits

Based on laravel-clickhouse.

License

MIT. See LICENSE.

vuthaihoc / laravel-matrixone

Package info

Security

Statistics