Laravel 13 now supports MariaDB Vector natively

Written by Written by Robert Silén Leave a comment on Laravel 13 now supports MariaDB Vector natively

If your Laravel application runs on MariaDB, you can add semantic search to it without a second database, an external vector service or an extra package. Since Laravel 13.28, vector columns, vector indexes and similarity queries work on MariaDB out of the box. A large part of that work came from community contributors, including Mohamed Touhami Rhaima.

Until this summer, Laravel’s built-in vector search was a PostgreSQL feature: it assumed pgvector. Laravel’s AI SDK documentation now reads: “Vector queries are currently supported on PostgreSQL connections using the pgvector extension, or on MariaDB 11.7 or later using its native vector support.”

If you read our June guest post by Erik Ros, MariaDB Vector in Laravel: insights on choosing an embedding model, you already know that MariaDB Vector can be used with Laravel. Erik built the laravel-mariadb-vector package because Laravel had no MariaDB vector support at all. Its 2,000 installs showed there was real demand. What is new is that the same capabilities are now part of Laravel itself. On Laravel 13 you no longer need a package for the basics, and Erik’s package remains the option for Laravel 12 applications.

For a Laravel team that already runs MariaDB, built-in support means the embeddings can live in the same database, in the same tables, as the data they describe. You back them up with your data, they stay consistent with your data, and you query them with the same Eloquent you already use.

What it looks like

With Laravel 13 and MariaDB 11.7 or later (11.8 LTS or 12.3 LTS recommended), point Laravel at MariaDB with the mariadb driver:

DB_CONNECTION=mariadb

Then it is a column, a cast and a query:

// Migration
$table->vector('embedding', dimensions: 1536)->index();

// Model
protected function casts(): array
{
    return ['embedding' => AsVector::class];
}

// Query
Document::query()
    ->whereVectorSimilarTo('embedding', 'best wineries in Napa Valley')
    ->limit(10)
    ->get();

With Laravel’s AI SDK installed, the search string is turned into an embedding for you. Add your provider’s API key to .env (configuration). Hosted providers such as OpenAI charge per token; Ollama runs locally for free. The model you choose also decides how good your results are; more on that below.

  • Full instructions: Laravel’s Querying Embeddings documentation.
  • A complete working example: Mohamed Touhami Rhaima’s reference application, verified end to end on MariaDB, with a Docker setup and a README.

Mohamed’s tips for MariaDB users

Mohamed, who did much of the work behind MariaDB support (more on that below), has two tips for anyone trying it:

  1. Use the mariadb driver, not mysql. Laravel has had a dedicated mariadb driver since Laravel 11. Pointed at a MariaDB server, the mysql driver appears to work, but vector queries and vector indexes throw exceptions.
  2. Skip Schema::ensureVectorExtensionExists(). It appears in the AI SDK documentation’s migration example, but it is a pgvector helper and throws exceptions on MariaDB. MariaDB needs no extension: VECTOR is a built-in type.

Which embedding model?

The database part is now the easy part. Which embedding model you choose, and how you call it, decides how good your search results are. That was the real subject of Erik’s June post. He tested 2,942 job titles in English and Dutch, and the share of correct top results went from 14 % to almost 60 % by changing the model and the way it is prompted. Read his post before you commit to a model. Remember that the column’s dimension count is a contract with the model you pick.

Who made it happen

Mohamed Touhami Rhaima is a full-stack PHP developer and project manager in Tunisia, and has built applications with Laravel for about six years.

In his own words:

I have used MariaDB for years. When I wanted to bring AI into my projects, I needed tools and practical tips to do it with Laravel and MariaDB, and they were not there yet. So I did my research and started closing the gaps one by one. I keep going because every gap closed helps other Laravel developers who run MariaDB.

Between mid-August and late September, he closed the gaps piece by piece:

  • Vector queries on MariaDB (laravel/framework#61250). Laravel’s vector query methods now compile to MariaDB’s VEC_DISTANCE_COSINE, with the first unit tests for vector queries.
  • Testing on the MariaDB versions that have vectors (#61615, #61641). Laravel’s CI only ran its database suite on MariaDB 10, so every test that needed 11.7 or later, including all the vector tests, was silently skipped on every pull request. It now also runs on 11.8 LTS and 12.3 LTS.
  • Documentation (laravel/docs#11368, #11374). He documented vector indexes and corrected outdated notes about MariaDB.

He wasn’t alone. Three more contributors, known on GitHub as michielvaneerd, eas4ai and xurshudyan, did important parts of the work:

  • michielvaneerd added vector indexes on MariaDB (#60334).
  • eas4ai fixed how vectors are bound on MariaDB and added the AsVector cast (#61337).
  • xurshudyan added dropVectorIndex() (#61391).

Taylor Otwell, who created Laravel and still leads it, reviewed and merged all of these pull requests.

What’s next

Mohamed is continuing, and these are the next steps he is working on:

  • Developing the reference application further. The reference application mentioned above is a first version. It currently works from the command line: it ingests markdown files and answers questions from them. Mohamed plans to add an “ask the docs” web endpoint and write a step-by-step tutorial on it for mariadb.org.
  • Euclidean distance and index tuning. Laravel core supports cosine distance. Euclidean distance and a configurable M for the vector index are in a separate package, laravel-vector-metrics. If you switch metric, create the index with the same one: MariaDB only uses a vector index when the query’s distance function matches it.
  • Hybrid search. MariaDB can combine full-text search and vector search in one SQL query. Mohamed is looking at how well Laravel’s whereFullText() works with MariaDB, as a step toward showing hybrid search in Laravel.

Tell us how it goes

If you run Laravel on MariaDB, try it on your own data, and tell us what works and what doesn’t, on MariaDB Zulip. Feedback on the reference application is welcome as issues on its repository. If you find a bug in Laravel’s MariaDB support, open an issue or a pull request on laravel/framework. As this summer showed, they get reviewed quickly.