Laravel Mariadb Vector Laravel Package

Product Decisions This Supports

• "Do we ship semantic search this quarter?" This package collapses that question from a platform program into a sprint-sized feature. Vector storage, indexing, and similarity ranking arrive as a migration, a model cast, and one query macro — no new service to procure, no dual-write pipeline, no second datastore to operate. If semantic search is a differentiator but not the business, this is the cheapest credible path to a shippable increment.
• Build vs. buy vs. adopt. It reframes the choice: not "Pinecone/Weaviate vs. build a search stack," but "adopt a thin adapter over capability we already pay for." The package's entire value-add is ergonomics — Eloquent macros that compile to native VEC_DISTANCE_* SQL. That means the underlying capability is portable knowledge, not lock-in, which de-risks the buy side of the decision.
• Feature scope: search, RAG retrieval, recommendations, dedupe, related-content. All are reachable with nearestNeighbors() plus a limit. Explicitly out of scope and therefore separate product decisions: embedding generation (the package is storage-and-search only, "bring your own embeddings"), reranking, hybrid keyword+vector search, and relevance tuning. Budget those as their own line items — the vendor choice for embeddings is a distinct, and probably larger, decision than this package.
• Roadmap sequencing tied to a platform prerequisite. Adoption is gated on MariaDB 11.7+ (not the 11.4 LTS), Laravel 12+, PHP 8.4+. So the real roadmap item is the database upgrade, with this package as a fast follow-on. A PM should sequence it that way and use "unlocks native vector search" as one of the upgrade's justifications, not the sole one.
• Infra-cost and data-governance decisions. "Zero external services" is a genuine product constraint in regulated or cost-sensitive contexts: embeddings and vectors never leave your database, there's no per-query vendor bill, and no new DPA to negotiate. That can be the deciding factor independent of technical merit.
• Scale-gated scope. Without a vector index it's a full table scan — fine for thousands of rows, degrading beyond. With an index, MariaDB allows only one VECTOR INDEX per table and requires the column to be NOT NULL. Those are hard product constraints: one primary embedding per entity, one searchable vector per table. Multi-vector or per-tenant-isolated search needs a different design, and a PM should know that before committing to a feature spec.

When to Consider This Package

Consider it when all of the following hold:

• You are already on, or have a funded and scheduled path to, MariaDB 11.7+ with Laravel 12 / PHP 8.4. If you're on 10.x, 11.4 LTS, or MySQL 8, this is a non-starter until that upgrade ships.
• The scope is one embedding per record, one searchable vector column per table, and a corpus in the thousands-to-low-millions range where ANN indexing is sufficient.
• You want speed of validation over depth of capability — an MVP, a spike, a pilot feature, or an internal tool.
• Data residency, cost predictability, or "no new vendor" are real constraints.
• You are prepared to own the code. The repository is archived: 9 stars, 0 dependents, single maintainer, no support contract, no security-response commitment. The correct posture is fork it internally — vendor the source, run the test suite, own the upgrade path. Approve it as a reference implementation you take responsibility for, not as a dependency you rely on.

Look elsewhere when:

• You need production SLA, security patching, or vendor accountability. An archived repo with no downstream users is a maintenance liability you must budget for explicitly.
• You need serious ANN scale or tuning (HNSW parameters, filtered vector search at high cardinality), multiple vector indexes per table, or dot-product distance (MariaDB doesn't support it).
• You're on Postgres — pgvector is the mature, maintained equivalent. If a database migration is on the table anyway, that's the more durable bet.
• You want an integrated retrieval stack (embedding pipeline, hybrid search, reranking, relevance evaluation) rather than primitives.

How to Pitch It (Stakeholders)

To executives: "We can offer semantic search — meaning-based, not keyword-based — without buying a vector database, signing a new vendor, or letting our content leave our infrastructure. The cost is roughly one sprint, plus it depends on a database upgrade we should be planning anyway. The catch: the open-source project is archived, so we'd adopt it as internal code we maintain rather than a supported product — which for a thin adapter is a small, bounded commitment, and it keeps our options open to move to a managed vector store later if scale demands it."

To engineering: "It's a narrow adapter, not a search engine. It gives us a vector column and index in migrations, a binary-safe cast that turns MariaDB's VECTOR into a PHP float array, and four query macros that compile to native VEC_DISTANCE_COSINE / VEC_DISTANCE_EUCLIDEAN over VEC_FromText(?). No new moving parts — blast radius is query construction and casting. Integration is composer require, a migration, a cast, under a day's work once we're on MariaDB 11.7+. What I want from you: fork it, run the test suite, decide whether we vendor or reimplement the ~three pieces we actually use. Also note a real bug shipped and was fixed in 1.2.1 — binary format misdetection on ~1 in 256 vectors — which tells us the binary boundary is the fragile part and deserves our own test coverage. Treat the SQL semantics as the durable asset; the wrapper is replaceable."