{"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/bd6b5437e6ad87bb49f9b426724f07a9f64e9683/src/Illuminate/Database/Query/Builder.php#L4761-L4797","documentation":"Thrown by Builder::ensureConnectionSupportsVectors() when orderByVectorDistance() is called on a connection that is not a PostgresConnection. Vector distance ordering compiles to the pgvector `<=>` operator which only exists on Postgres with the pgvector extension. Laravel refuses to emit it for other engines because the SQL would be rejected at the database level.","triggerScenarios":"Calling orderByVectorDistance($column, $vector) (or passing a vector string) on a query builder whose underlying connection is MySQL, SQLite, or SQL Server. The check happens in ensureConnectionSupportsVectors() via `instanceof PostgresConnection` before any SQL is built.","commonSituations":"Developing AI/RAG features locally against SQLite or MySQL, then deploying the same code expecting Postgres. Forgetting to install/enable the pgvector extension on the Postgres connection also surfaces nearby failures. Running tests against an in-memory SQLite database that share query code with production Postgres.","solutions":["Switch the DB connection to Postgres (config/database.php) and install the pgvector extension for the vector column type.","If you must support multiple engines, branch on $builder->getConnection()->getDriverName() === 'pgsql' before calling orderByVectorDistance.","For local/test parity, run tests against a Postgres (with pgvector) container instead of SQLite."],"exampleFix":"// before\n$posts = DB::table('documents')->orderByVectorDistance('embedding', $vec)->get();\n\n// after (guard by driver)\n$query = DB::table('documents');\nif ($query->getConnection()->getDriverName() === 'pgsql') {\n    $query->orderByVectorDistance('embedding', $vec);\n}\n$posts = $query->get();","handlingStrategy":"validation","validationCode":"// Check before calling orderByVectorDistance\nif ($builder->getConnection() instanceof \\Illuminate\\Database\\PostgresConnection) {\n    $builder->orderByVectorDistance('embedding', $vector);\n} else {\n    throw new \\LogicException('Vector distance ordering requires a Postgres connection with pgvector.');\n}","typeGuard":"function supportsVectorDistance(\\Illuminate\\Database\\Query\\Builder $query): bool\n{\n    return $query->getConnection() instanceof \\Illuminate\\Database\\PostgresConnection;\n}","tryCatchPattern":null,"preventionTips":["Centralise vector queries in a repository that asserts the Postgres driver.","Keep production and test databases both on Postgres+pgvector to avoid engine drift.","Document the pgvector requirement wherever orderByVectorDistance is used."],"tags":["postgres","vector","ai","database-engine","pgvector"],"analyzedSha":"bd6b5437e6ad87bb49f9b426724f07a9f64e9683","analyzedAt":"2026-08-06T00:28:32.783Z","schemaVersion":2}