README

PostgreSQL pgvector driver for x-laravel/embedding.

How It Works

• Implements SimilarityDriver — registers as the pgsql driver, similarity search runs entirely in PostgreSQL using pgvector's <=> cosine distance operator
• No custom VectorStore needed — pgvector's text format ([1.0, 2.0, ...]) is valid JSON, so the core JSON storage works transparently

Requirements

• PHP ^8.3
• Laravel ^12.0 | ^13.0
• x-laravel/embedding ^1.0
• PostgreSQL with pgvector extension

Installation

composer require x-laravel/embedding-pgsql-driver

The PgsqlEmbeddingServiceProvider is auto-discovered and registers the pgsql driver automatically.

Setup

1. Configure x-laravel/embedding

Publish the config if you haven't already:

php artisan vendor:publish --tag=embedding-config

Set the similarity driver and database connection in config/embedding.php:

'database' => [
    'connection' => env('EMBEDDINGS_DATABASE_CONNECTION', env('DB_CONNECTION', 'pgsql')),
    'table'      => env('EMBEDDINGS_DB_TABLE', 'embeddings'),
],

'similarity' => [
    'driver' => env('EMBEDDING_SIMILARITY_DRIVER', 'auto'),
],

2. Create the embeddings table

This driver ships its own PostgreSQL-native migration that replaces the default one from x-laravel/embedding. It enables the pgvector extension and creates a vector(1536) column.

Run the migration:

php artisan migrate

If you need to customise the DDL, publish the migration first:

php artisan vendor:publish --tag=embedding-pgsql-migrations
php artisan migrate

Note: CREATE EXTENSION IF NOT EXISTS vector requires CREATE privilege on the database. On managed platforms (RDS, Supabase, Cloud SQL), enable the extension separately with elevated privileges before running the migration.

3. Model

Follow the standard x-laravel/embedding setup. No PostgreSQL-specific changes are needed on your models.

use XLaravel\Embedding\Attributes\EmbedOn;
use XLaravel\Embedding\Concerns\Embeddable;
use XLaravel\Embedding\Contracts\HasEmbeddings;

#[EmbedOn(['title', 'body'])]
class Post extends Model implements HasEmbeddings
{
    use Embeddable;

    public function toEmbeddingText(): string
    {
        return $this->title.' '.$this->body;
    }
}

Usage

The driver is transparent — use the standard x-laravel/embedding API:

Post::similarToText('web framework', limit: 10);
Post::similarTo($vector, limit: 10, threshold: 0.8);
Post::rankByRelevance($posts, 'web framework');

$post->mostSimilar(limit: 5);
$post->similarityTo($otherPost);

All methods set a similarity_score float attribute on each returned model.

Testing

# Build first (once per PHP version)
DOCKER_BUILDKIT=0 docker compose --profile php83 build

# Run tests
docker compose --profile php83 up
docker compose --profile php84 up
docker compose --profile php85 up

License

This package is open-sourced software licensed under the MIT license.