laravel/framework · error · RuntimeException

Vector distance queries are only supported by Postgres.

Error message

Vector distance queries are only supported by Postgres.

What it means

Laravel's vector distance query builder methods (selectVectorDistance, whereVectorDistanceLessThan, whereVectorSimilarTo, orderByVectorDistance) call ensureConnectionSupportsVectors(), which checks whether the active connection is a PostgresConnection. Only PostgreSQL with the pgvector extension supports vector similarity search, so any non-Postgres connection is rejected at runtime before SQL compilation.

Solutions

Set DB_CONNECTION=pgsql in .env and ensure a PostgreSQL server with the pgvector extension is available
In the test suite, switch to a Postgres-based testing setup (e.g., RefreshDatabase with a pgsql connection) instead of SQLite
If you must run non-Postgres locally, guard the vector query calls behind a connection check and skip or stub them
Verify the extension is installed: run CREATE EXTENSION IF NOT EXISTS vector; on the target database

Example fix

// before — fails on SQLite/MySQL
DB::table('documents')->whereVectorSimilarTo('embedding', $query, 0.6)->get();

// after — guard by connection type
if (DB::connection() instanceof \Illuminate\Database\PostgresConnection) {
    DB::table('documents')->whereVectorSimilarTo('embedding', $query, 0.6)->get();
} else {
    // fallback: keyword search or external vector store
}

Defensive patterns

Strategy: type-guard

Validate before calling

use Illuminate\Database\Connection;
use Illuminate\Database\PostgresConnection;

if (DB::connection() instanceof PostgresConnection) {
    // safe to use vector distance queries
    $results = DB::table('docs')->whereVectorDistanceLessThan('embedding', $vector, 0.5)->get();
} else {
    // use fallback search strategy
}

Type guard

function supportsVectorQueries(): bool {
    return DB::connection() instanceof \Illuminate\Database\PostgresConnection;
}

Try / catch

try {
    DB::table('docs')->whereVectorSimilarTo('embedding', $vec, 0.6)->get();
} catch (\RuntimeException $e) {
    if (str_contains($e->getMessage(), 'Vector distance')) {
        // fallback: keyword search or external vector store
    } else {
        throw $e;
    }
}

Prevention

Check DB_CONNECTION=pgsql in .env before writing code that uses vector methods
Document which features require PostgreSQL in the project README or AGENTS.md
In multi-DB test suites, guard vector queries with instanceof PostgresConnection
Run CREATE EXTENSION IF NOT EXISTS vector; in migrations to ensure pgvector is installed

When it happens

Trigger: Calling any vector method on a query builder whose connection is not 'pgsql': DB::table('docs')->whereVectorDistanceLessThan('embedding', $vec, 0.5), ->selectVectorDistance('embedding', $vec), ->orderByVectorDistance('embedding', $vec), or ->whereVectorSimilarTo('embedding', $vec, 0.6) when DB_CONNECTION is sqlite, mysql, or sqlsrv.

Common situations: Running tests with DB_CONNECTION=sqlite or an in-memory SQLite database while the application uses vector queries. Configuring DB_CONNECTION to mysql or sqlsrv in .env while the codebase relies on pgvector features. Misidentifying the active connection due to multi-database setups where read/write connections differ.

Related errors

AI-assisted analysis of laravel/framework@e0f6eb3518 (2026-08-11). Data as JSON: /api/errors/3d3a2a4c7b32f20c. Report an issue: GitHub.

Appendix: source

Thrown at src/Illuminate/Database/Query/Builder.php:4779

     *
     * @return \Illuminate\Database\ConnectionInterface
     */
    public function getConnection()
    {
        return $this->connection;
    }

    /**
     * Ensure the database connection supports vector queries.
     *
     * @return void
     *
     * @throws \RuntimeException
     */
    protected function ensureConnectionSupportsVectors()
    {
        if (! $this->connection instanceof PostgresConnection) {
            throw new RuntimeException('Vector distance queries are only supported by Postgres.');
        }
    }

    /**
     * Get the database query processor instance.
     *
     * @return \Illuminate\Database\Query\Processors\Processor
     */
    public function getProcessor()
    {
        return $this->processor;
    }

    /**
     * Get the query grammar instance.
     *
     * @return \Illuminate\Database\Query\Grammars\Grammar
     */

View on GitHub (pinned to e0f6eb3518)