Download the PHP package illuma-law/laravel-vector-schema without Composer

Laravel Vector Schema

Portable vector columns and search macros for Laravel Eloquent.

When building AI applications with RAG (Retrieval-Augmented Generation), you must store and query high-dimensional vector embeddings. However, PostgreSQL (pgvector), SQLite (sqlite-vec), SingleStore, and MySQL all use different syntax for vector data types, index creation, and cosine distance calculations.

This package provides Laravel Blueprint schema macros and Eloquent Builder macros to seamlessly abstract away these database differences, giving you a unified API for vector search across all supported databases.

Features

• Database Portability: Write your migrations and vector queries once; the package compiles them to the correct syntax for your active database connection.
• SQLite Binary Support: Safely handles the complex float32 BLOB packing required by sqlite-vec while using native vector column types on Postgres/MySQL.
• HNSW Index Support: Provides a macro for creating high-performance Approximate Nearest Neighbor (ANN) indexes.
• Cosine Similarity: Provides fluent query macros to filter, sort, and select based on vector cosine similarity and distance.
• Eloquent Cast: Automatically serializes and deserializes PHP arrays to the correct database vector format.

Database Support Matrix

Note: MySQL Community Edition (GPL) currently restricts the VECTOR_DISTANCE function to HeatWave/Enterprise users. SQLite requires loading the sqlite-vec extension.

Installation

You can install the package via composer:

The Service Provider will automatically register the Blueprint and Builder macros.

Usage & Integration

Schema Migrations

Use the vectorColumn macro to define portable vector columns. On PostgreSQL, MySQL, MariaDB, SQL Server, and SingleStore, this creates a native vector column. On SQLite, it safely falls back to a BLOB column compatible with sqlite-vec.

Use hnswIndex for high-performance approximate nearest neighbor (ANN) similarity search. This generates a native HNSW index on PostgreSQL and is gracefully ignored on other drivers.

Eloquent Casts

Add the VectorArray cast to your Eloquent model. This handles the serialization and deserialization of plain PHP arrays into the specific formats required by your active database driver.

Now you can interact with the vector just like a normal array:

Vector Math Utilities (VectorProcessor)

When dealing with high-dimensional vectors, you often need to perform common mathematical operations such as normalizing input data or averaging several vectors (e.g., to create a centroid for a cluster or a search query).

The package includes a domain-agnostic VectorProcessor class for these tasks.

normalizeVector

Ensures an input vector is a flat list of floats, filters out NaN or INF values, and validates the expected dimensionality. Returns an empty array if the input is invalid.

averageVectors

Computes the mathematical average (centroid) of a collection of vectors. This is useful for combining multiple embeddings into a single query vector.

Vector Querying (Semantic Search)

The package provides several macros attached to the Laravel Query Builder.

whereHybridVectorSimilarTo

Filter results to only include those that meet a minimum cosine similarity threshold. You can also ask the macro to automatically order the results by similarity (closest first).

selectHybridVectorDistance

Select the raw cosine distance between a stored vector and your query vector into a dynamically named alias. Note that distance is the inverse of similarity (0.0 is an exact match).

whereHybridVectorDistanceLessThan

If you prefer thinking in distances rather than similarities, directly filter by the raw distance.

orderByHybridVectorDistance

If you only need to order results by semantic proximity without filtering or selecting the specific distance value:

Testing

The package includes a comprehensive test suite using Pest.

License

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