{"record":{"id":"0248a878675b5460","repo":"laravel/framework","slug":"this-database-engine-does-not-support-json-contain","errorCode":null,"errorMessage":"This database engine does not support JSON contains operations.","messagePattern":"This database engine does not support JSON contains operations\\.","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"src/Illuminate/Database/Query/Grammars/Grammar.php","lineNumber":710,"sourceCode":"\n        return $not.$this->compileJsonContains(\n            $where['column'],\n            $this->parameter($where['value'])\n        );\n    }\n\n    /**\n     * Compile a \"JSON contains\" statement into SQL.\n     *\n     * @param  string  $column\n     * @param  string  $value\n     * @return string\n     *\n     * @throws \\RuntimeException\n     */\n    protected function compileJsonContains($column, $value)\n    {\n        throw new RuntimeException('This database engine does not support JSON contains operations.');\n    }\n\n    /**\n     * Compile a \"where JSON overlaps\" clause.\n     *\n     * @param  \\Illuminate\\Database\\Query\\Builder  $query\n     * @param  array  $where\n     * @return string\n     */\n    protected function whereJsonOverlaps(Builder $query, $where)\n    {\n        $not = $where['not'] ? 'not ' : '';\n\n        return $not.$this->compileJsonOverlaps(\n            $where['column'],\n            $this->parameter($where['value'])\n        );\n    }","sourceCodeStart":692,"sourceCodeEnd":728,"githubUrl":"https://github.com/laravel/framework/blob/e0f6eb3518ac29fbbca8529e97d0df7fc9f24481/src/Illuminate/Database/Query/Grammars/Grammar.php#L692-L728","documentation":"The base Grammar's compileJsonContains throws by default. All four major engine grammars (MySqlGrammar, PostgresGrammar, SQLiteGrammar, SqlServerGrammar) override it with engine-specific JSON_CONTAINS / jsonb @> / JSON functions. This error only fires for a custom grammar that extends the base Grammar directly without overriding the method.","triggerScenarios":"Using whereJsonContains() on a query builder whose grammar is a custom class extending Illuminate\\Database\\Query\\Grammars\\Grammar without implementing compileJsonContains. This would occur with a third-party or community database driver that does not yet support JSON operations.","commonSituations":"Integrating a community database package (e.g., a ClickHouse or Trino driver) that extends the base Grammar but has not implemented JSON contains. Using an outdated version of a driver package that predates JSON support.","solutions":["Switch to a built-in connection (mysql, pgsql, sqlite, or sqlsrv) — all four override compileJsonContains","If using a custom grammar, override compileJsonContains in your grammar class to emit the correct SQL for your engine","Replace whereJsonContains with a raw clause that uses your engine's native JSON function"],"exampleFix":"// before — custom grammar without JSON support\nDB::table('users')->whereJsonContains('roles', 'admin')->get();\n\n// after — raw clause for a JSON-capable custom engine\nDB::table('users')->whereRaw(\"json_contains(roles, '\\\"admin\\\"')\")->get();","handlingStrategy":"try-catch","validationCode":"if (method_exists(DB::connection()->getQueryGrammar(), 'compileJsonContains')) {\n    $reflection = new ReflectionMethod(DB::connection()->getQueryGrammar(), 'compileJsonContains');\n    if ($reflection->getDeclaringClass()->getName() !== 'Illuminate\\\\Database\\\\Query\\\\Grammars\\\\Grammar') {\n        DB::table('users')->whereJsonContains('roles', 'admin')->get();\n    }\n}","typeGuard":"function grammarSupportsJsonContains(): bool {\n    $grammar = DB::connection()->getQueryGrammar();\n    $method = new ReflectionMethod($grammar, 'compileJsonContains');\n    return $method->getDeclaringClass()->getName() !== 'Illuminate\\\\Database\\\\Query\\\\Grammars\\\\Grammar';\n}","tryCatchPattern":"try {\n    DB::table('users')->whereJsonContains('roles', 'admin')->get();\n} catch (\\RuntimeException $e) {\n    if (str_contains($e->getMessage(), 'JSON contains')) {\n        // fallback: raw JSON function or denormalized column\n        DB::table('users')->whereRaw(\"roles LIKE '%admin%'\")->get();\n    } else {\n        throw $e;\n    }\n}","preventionTips":["Use a built-in connection (mysql, pgsql, sqlite, sqlsrv) — all four support JSON contains","If building a custom grammar, override compileJsonContains before using whereJsonContains","Test JSON operations early in custom driver integration"],"tags":["json","grammar","database","custom-driver"],"backgroundTag":null,"analyzedSha":"e0f6eb3518ac29fbbca8529e97d0df7fc9f24481","analyzedAt":"2026-08-11T20:52:37.562Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}