{"record":{"id":"6b56a0079cd28fb1","repo":"laravel/framework","slug":"this-database-engine-does-not-support-json-overlap","errorCode":null,"errorMessage":"This database engine does not support JSON overlaps operations.","messagePattern":"This database engine does not support JSON overlaps operations\\.","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"src/Illuminate/Database/Query/Grammars/Grammar.php","lineNumber":741,"sourceCode":"\n        return $not.$this->compileJsonOverlaps(\n            $where['column'],\n            $this->parameter($where['value'])\n        );\n    }\n\n    /**\n     * Compile a \"JSON overlaps\" statement into SQL.\n     *\n     * @param  string  $column\n     * @param  string  $value\n     * @return string\n     *\n     * @throws \\RuntimeException\n     */\n    protected function compileJsonOverlaps($column, $value)\n    {\n        throw new RuntimeException('This database engine does not support JSON overlaps operations.');\n    }\n\n    /**\n     * Prepare the binding for a \"JSON contains\" statement.\n     *\n     * @param  mixed  $binding\n     * @return string\n     */\n    public function prepareBindingForJsonContains($binding)\n    {\n        return json_encode($binding, JSON_UNESCAPED_UNICODE);\n    }\n\n    /**\n     * Compile a \"where JSON contains key\" clause.\n     *\n     * @param  \\Illuminate\\Database\\Query\\Builder  $query\n     * @param  array  $where","sourceCodeStart":723,"sourceCodeEnd":759,"githubUrl":"https://github.com/laravel/framework/blob/e0f6eb3518ac29fbbca8529e97d0df7fc9f24481/src/Illuminate/Database/Query/Grammars/Grammar.php#L723-L759","documentation":"The base Grammar's compileJsonOverlaps throws by default. Only MySqlGrammar overrides it (using JSON_OVERLAPS, available in MySQL 8.0.17+ and MariaDB 10.9+). PostgreSQL, SQLite, and SQL Server grammars do not override it, so whereJsonOverlaps on those connections triggers the throw. JSON overlap checks whether two JSON arrays share at least one element.","triggerScenarios":"Calling ->whereJsonOverlaps('tags', ['php', 'laravel']) or ->orWhereJsonOverlaps on a PostgreSQL, SQLite, or SQL Server connection.","commonSituations":"Developer assumes JSON_OVERLAPS is a standard SQL function. Code written for MySQL/MariaDB then deployed against PostgreSQL. Test suite running on SQLite while production uses MySQL.","solutions":["Switch to a MySQL 8.0.17+ or MariaDB 10.9+ connection — the only grammars that override compileJsonOverlaps","On PostgreSQL, rewrite as ->whereJsonContains('tags', 'php')->orWhereJsonContains('tags', 'laravel') (PostgreSQL supports JSON contains via jsonb @>)","On SQLite/SQL Server, use a raw WHERE with EXISTS + json_each (SQLite) or OPENJSON (SQL Server)","Use a separate junction/relationship table instead of JSON arrays for overlapping tag queries"],"exampleFix":"// before — fails on PostgreSQL / SQLite / SQL Server\nProduct::whereJsonOverlaps('tags', ['php', 'laravel'])->get();\n\n// after — works on PostgreSQL (which supports jsonb contains)\nProduct::where(function ($q) {\n    $q->whereJsonContains('tags', 'php')->orWhereJsonContains('tags', 'laravel');\n})->get();","handlingStrategy":"type-guard","validationCode":"$driver = DB::connection()->getDriverName();\n\nif ($driver === 'mysql') {\n    $query->whereJsonOverlaps('tags', ['php', 'laravel']);\n} else {\n    // fallback: chain whereJsonContains for each value\n    $query->where(function ($q) use ($tags) {\n        foreach ($tags as $tag) {\n            $q->orWhereJsonContains('tags', $tag);\n        }\n    });\n}","typeGuard":"function supportsJsonOverlaps(): bool {\n    return DB::connection()->getDriverName() === 'mysql';\n}","tryCatchPattern":"try {\n    $query->whereJsonOverlaps('tags', ['php', 'laravel']);\n} catch (\\RuntimeException $e) {\n    if (str_contains($e->getMessage(), 'JSON overlaps')) {\n        $query->where(function ($q) {\n            $q->whereJsonContains('tags', 'php')->orWhereJsonContains('tags', 'laravel');\n        });\n    } else {\n        throw $e;\n    }\n}","preventionTips":["Treat whereJsonOverlaps as MySQL/MariaDB-only","For PostgreSQL, chain whereJsonContains calls as a portable alternative","Consider a normalized junction table for tag overlap queries across engines"],"tags":["json","overlaps","mysql","database","grammar"],"backgroundTag":null,"analyzedSha":"e0f6eb3518ac29fbbca8529e97d0df7fc9f24481","analyzedAt":"2026-08-11T20:52:37.562Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}