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

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.