Download the PHP package devilsberg/laravel-mariadb-vector without Composer

Laravel MariaDB Vector

MariaDB 11.7+ native vector storage and search for Laravel.

This package brings vector column support, binary-safe casting, and similarity search macros to Eloquent — powered by MariaDB's native VECTOR type and VEC_DISTANCE_* functions. Think of it as the MariaDB equivalent of pgvector for Laravel.

Requirements

• PHP 8.4+
• Laravel 12+
• MariaDB 11.7+

Installation

Publish the config file:

Quick Start

1. Create a migration

2. Set up your model

3. Store a vector

4. Search by similarity

Vector Indexes

Without a vector index every similarity search performs a full table scan — fine for thousands of rows, slow at scale. MariaDB 11.7 supports VECTOR INDEX for approximate nearest neighbor (ANN) lookups, exposed via the standard vectorIndex() Blueprint method that Laravel 12 provides.

Adding an index in a migration

Custom index name

By default the index name follows Laravel's standard index naming — {table}_{column}_vectorindex:

Adding an index to an existing table

Note: MariaDB requires the vector column to be NOT NULL to add a vector index. Attempting to index a nullable vector column will raise a database error.

Note: MariaDB 11.7 supports only one VECTOR INDEX per table. Attempting to add a second one will raise a database error.

Bring Your Own Embeddings

This package handles storage and search only. You generate embeddings however you want — Ollama, Mistral, Cohere, a local Python model, or anything that produces a float array.

VectorCast

VectorCast handles conversion between MariaDB's binary VECTOR format and PHP float arrays.

• Reading: Decodes MariaDB's binary packed floats (32-bit IEEE 754) or JSON string format to array<float>
• Writing: Converts array<float> to a VEC_FromText('[0.1, 0.2, ...]') expression
• Null-safe: Returns null for null values in both directions
• Empty-safe: Returns null for empty arrays

The column supports ->nullable() in migrations:

Query Builder Macros

All macros are registered on Illuminate\Database\Eloquent\Builder.

whereVectorSimilarTo

Filter results by vector distance threshold.

Generates: WHERE VEC_DISTANCE_COSINE(\embedding`, VEC_FromText(?)) < ?`

orderByVectorDistance

Sort results by vector distance (nearest first).

Generates: ORDER BY VEC_DISTANCE_COSINE(\embedding`, VEC_FromText(?)) asc`

selectVectorDistance

Include the distance score in query results.

Generates: VEC_DISTANCE_COSINE(\embedding`, VEC_FromText(?)) as `score``

nearestNeighbors

The recommended macro for most use cases. Computes the distance once per row as a normalized score column and orders results by highest score first. More efficient than chaining the three individual macros.

Generates:

The score is a normalized similarity value — higher means more similar:

• Cosine: 1.0 - distance, range approximately [-1, 1] (in practice [0, 1] for LLM embeddings)
• Euclidean: 1.0 - distance / SQRT(2), normalized to approximately [0, 1]

Combining macros

For advanced queries where you need threshold filtering alongside ordering, use the individual macros:

Configuration

Published to config/vector.php:

Note: DOT product distance is not supported by MariaDB. Configuring it will throw an InvalidArgumentException.

Testing

Run the unit tests:

Run the integration tests (requires a live MariaDB instance):

Configure MariaDB credentials in phpunit.xml:

Run the full suite:

Support

If this package saves you time, consider buying me a coffee.

License

The MIT License (MIT). Please see License File for more information.