Laravel Matrixone Laravel Package

Getting Started

Install the package and let Laravel package discovery register it:

composer require vuthaihoc/laravel-matrixone

Add a named MatrixOne connection in config/database.php rather than replacing your default database immediately:

'matrixone' => [
    'driver' => 'matrixone',
    'host' => env('MATRIXONE_HOST', '127.0.0.1'),
    'port' => env('MATRIXONE_PORT', '6001'),
    'database' => env('MATRIXONE_DATABASE'),
    'username' => env('MATRIXONE_USERNAME'),
    'password' => env('MATRIXONE_PASSWORD'),
    'charset' => 'utf8mb4',
    'collation' => 'utf8mb4_unicode_ci',
    'prefix' => '',
],

Set MATRIXONE_* values in .env, then smoke-test the connection:

php artisan tinker

DB::connection('matrixone')->select('select 1');

Look first at the package README, the service provider/connector source, and any publishable config. Confirm whether the package registers the matrixone driver automatically or whether you must add a provider/connector binding manually.

A safe first use case is a read-only reporting or analytics query against an existing MatrixOne table. Once that works, try php artisan migrate --database=matrixone against a disposable database before pointing application migrations at it.

Implementation Patterns

Use MatrixOne as an explicit named connection. This keeps MySQL and MatrixOne behavior isolated:

DB::connection('matrixone')->table('events')->latest()->limit(10)->get();

For Eloquent models, set the connection explicitly:

class Event extends Model
{
    protected $connection = 'matrixone';
}

For migrations, target the connection either from the command or in the schema builder:

php artisan migrate --database=matrixone

Schema::connection('matrixone')->create('events', function (Blueprint $table) {
    $table->id();
    $table->string('name');
    $table->timestamps();
});

Keep MatrixOne-specific SQL behind a repository or service class. MatrixOne is MySQL-protocol compatible, but raw SQL and schema features can diverge from MySQL. Isolating those queries makes upgrades and testing easier.

For multi-database applications, wrap writes in the correct connection transaction:

DB::connection('matrixone')->transaction(function () {
    DB::connection('matrixone')->table('events')->insert([...]);
});

Do not assume cross-connection transactions are atomic. If a workflow writes to MySQL and MatrixOne, handle compensation/failure explicitly.

Use a health check in CI or deployment:

DB::connection('matrixone')->getPdo();

For debugging, enable the query log on that connection:

DB::connection('matrixone')->enableQueryLog();

Gotchas and Tips

MatrixOne is not a drop-in replacement for every MySQL feature. Validate migrations, indexes, foreign keys, JSON behavior, generated columns, collations, and unsupported schema operations before running them in production. If Laravel’s MySQL grammar emits SQL MatrixOne rejects, use raw statements or a custom grammar/connector rather than forcing the migration.

Watch the port. MatrixOne commonly uses 6001, not MySQL’s 3306. Connection failures are often host/port, auth, or missing driver registration issues.

Treat v1.2.1 as a patch-level release. No breaking changes are implied by semver, but the release notes only link to the changelog. Before upgrading, review the diff for connector/grammar changes, pin the version in composer.json, and run an integration test against a real MatrixOne instance.

Clear config after changing connection settings:

php artisan config:clear

Be careful with migrate:fresh, db:wipe, and destructive schema commands on a MatrixOne connection. Test them only against disposable databases.

If query builder features such as upsert, insertOrIgnore, lockForUpdate, or pagination behave unexpectedly, reproduce the issue with raw SQL first. That separates Laravel grammar problems from MatrixOne SQL support.

Use UTC consistently and set timezone/charset options deliberately in the connection config. Table and column case sensitivity can also differ from MySQL expectations, especially when migrating existing schemas.

For extension, prefer a custom connector or query grammar bound through the package service provider if MatrixOne needs behavior beyond the default driver. Keep the custom binding in application code so package upgrades remain straightforward.