{"record":{"id":"3d3a2a4c7b32f20c","repo":"laravel/framework","slug":"vector-distance-queries-are-only-supported-by-post","errorCode":null,"errorMessage":"Vector distance queries are only supported by Postgres.","messagePattern":"Vector distance queries are only supported by Postgres\\.","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"src/Illuminate/Database/Query/Builder.php","lineNumber":4779,"sourceCode":"     *\n     * @return \\Illuminate\\Database\\ConnectionInterface\n     */\n    public function getConnection()\n    {\n        return $this->connection;\n    }\n\n    /**\n     * Ensure the database connection supports vector queries.\n     *\n     * @return void\n     *\n     * @throws \\RuntimeException\n     */\n    protected function ensureConnectionSupportsVectors()\n    {\n        if (! $this->connection instanceof PostgresConnection) {\n            throw new RuntimeException('Vector distance queries are only supported by Postgres.');\n        }\n    }\n\n    /**\n     * Get the database query processor instance.\n     *\n     * @return \\Illuminate\\Database\\Query\\Processors\\Processor\n     */\n    public function getProcessor()\n    {\n        return $this->processor;\n    }\n\n    /**\n     * Get the query grammar instance.\n     *\n     * @return \\Illuminate\\Database\\Query\\Grammars\\Grammar\n     */","sourceCodeStart":4761,"sourceCodeEnd":4797,"githubUrl":"https://github.com/laravel/framework/blob/e0f6eb3518ac29fbbca8529e97d0df7fc9f24481/src/Illuminate/Database/Query/Builder.php#L4761-L4797","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before — fails on SQLite/MySQL\nDB::table('documents')->whereVectorSimilarTo('embedding', $query, 0.6)->get();\n\n// after — guard by connection type\nif (DB::connection() instanceof \\Illuminate\\Database\\PostgresConnection) {\n    DB::table('documents')->whereVectorSimilarTo('embedding', $query, 0.6)->get();\n} else {\n    // fallback: keyword search or external vector store\n}","handlingStrategy":"type-guard","validationCode":"use Illuminate\\Database\\Connection;\nuse Illuminate\\Database\\PostgresConnection;\n\nif (DB::connection() instanceof PostgresConnection) {\n    // safe to use vector distance queries\n    $results = DB::table('docs')->whereVectorDistanceLessThan('embedding', $vector, 0.5)->get();\n} else {\n    // use fallback search strategy\n}","typeGuard":"function supportsVectorQueries(): bool {\n    return DB::connection() instanceof \\Illuminate\\Database\\PostgresConnection;\n}","tryCatchPattern":"try {\n    DB::table('docs')->whereVectorSimilarTo('embedding', $vec, 0.6)->get();\n} catch (\\RuntimeException $e) {\n    if (str_contains($e->getMessage(), 'Vector distance')) {\n        // fallback: keyword search or external vector store\n    } else {\n        throw $e;\n    }\n}","preventionTips":["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"],"tags":["vector","postgres","database","ai","connection"],"backgroundTag":null,"analyzedSha":"e0f6eb3518ac29fbbca8529e97d0df7fc9f24481","analyzedAt":"2026-08-11T20:52:37.562Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}