{"id":"74068b23795d943e","repo":"laravel/framework","slug":"this-database-engine-does-not-support-upserts","errorCode":null,"errorMessage":"This database engine does not support upserts.","messagePattern":"This database engine does not support upserts\\.","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"src/Illuminate/Database/Query/Grammars/Grammar.php","lineNumber":1420,"sourceCode":"        $joins = $this->compileJoins($query, $query->joins);\n\n        return \"update {$table} {$joins} set {$columns} {$where}\";\n    }\n\n    /**\n     * Compile an \"upsert\" statement into SQL.\n     *\n     * @param  \\Illuminate\\Database\\Query\\Builder  $query\n     * @param  array  $values\n     * @param  array  $uniqueBy\n     * @param  array  $update\n     * @return string\n     *\n     * @throws \\RuntimeException\n     */\n    public function compileUpsert(Builder $query, array $values, array $uniqueBy, array $update)\n    {\n        throw new RuntimeException('This database engine does not support upserts.');\n    }\n\n    /**\n     * Prepare the bindings for an update statement.\n     *\n     * @param  array  $bindings\n     * @param  array  $values\n     * @return array\n     */\n    public function prepareBindingsForUpdate(array $bindings, array $values)\n    {\n        $cleanBindings = Arr::except($bindings, ['select', 'join']);\n\n        $values = Arr::flatten(array_map(fn ($value) => value($value), $values));\n\n        return array_values(\n            array_merge($bindings['join'], $values, Arr::flatten($cleanBindings))\n        );","sourceCodeStart":1402,"sourceCodeEnd":1438,"githubUrl":"https://github.com/laravel/framework/blob/bd6b5437e6ad87bb49f9b426724f07a9f64e9683/src/Illuminate/Database/Query/Grammars/Grammar.php#L1402-L1438","documentation":"The base Grammar::compileUpsert() throws because this engine has no single-statement upsert (INSERT ... ON DUPLICATE KEY / ON CONFLICT / MERGE) that the grammar can compile. All four bundled grammars override compileUpsert, so this base throw is only reached by a custom Grammar subclass that does not implement upserts.","triggerScenarios":"Calling upsert($values, $uniqueBy, $update) on a connection whose grammar extends the base Grammar without overriding compileUpsert. No bundled driver reaches this base method.","commonSituations":"Building a new database driver integration that has not implemented upsert. Using a third-party grammar package that is incomplete.","solutions":["Implement compileUpsert($query, $values, $uniqueBy, $update) on the custom Grammar using the engine's native upsert syntax (e.g. MERGE).","Switch to one of the bundled connections.","Replace upsert() with a manual select-then-insert/update sequence."],"exampleFix":"// before (custom grammar)\nDB::table('users')->upsert($rows, ['email'], ['name']);\n// throws base Grammar::compileUpsert\n\n// after\nprotected function compileUpsert(Builder $query, array $values, array $uniqueBy, array $update)\n{\n    // emit engine-native MERGE / ON CONFLICT equivalent\n}","handlingStrategy":"validation","validationCode":"$driver = $query->getConnection()->getDriverName();\nif (! in_array($driver, ['mysql','sqlite','pgsql','sqlsrv'])) {\n    throw new \\LogicException('upsert is not supported by this engine.');\n}\nDB::table('users')->upsert($rows, ['email'], ['name']);","typeGuard":"function supportsUpsert(\\Illuminate\\Database\\Connection $connection): bool\n{\n    return method_exists($connection->getQueryGrammar(), 'compileUpsert');\n}","tryCatchPattern":null,"preventionTips":["Implement compileUpsert on custom grammars before exposing upsert().","Use bundled drivers for upsert-heavy code.","Add an upsert capability test for new driver integrations."],"tags":["upsert","custom-grammar","database-engine","insert-update"],"analyzedSha":"bd6b5437e6ad87bb49f9b426724f07a9f64e9683","analyzedAt":"2026-08-06T00:28:32.783Z","schemaVersion":2}