Por que whereNull não funciona com updateOrCreate no Laravel (e como evitar bugs silenciosos)

O updateOrCreate() é um dos métodos mais utilizados no Eloquent para garantir que registros sejam atualizados ou criados sem duplicações. Porém, muitos desenvolvedores (inclusive os mais experientes) acabam caindo numa armadilha silenciosa: o uso de campos NULL — especialmente o deleted_at — na cláusula de condição.

Se você já escreveu algo assim:

Model::updateOrCreate([
    'user_id' => $id,
    'deleted_at' => null,
], [...]);

⚠️ Pare agora. Isso não funciona como você pensa.

🔍 O problema

O updateOrCreate() do Eloquent traduz internamente o array de condições em comparações simples =. Então quando você faz 'deleted_at' => null, o Laravel não gera um WHERE deleted_at IS NULL, e sim:

WHERE deleted_at = null

O problema? Em SQL, = NULL nunca é verdadeiro. O resultado é que:

• Nenhum registro é encontrado,

• Eloquent presume que precisa criar um novo,

• E você acaba com registros duplicados, mesmo que pareça que está fazendo tudo certo.

✅ A solução correta

$registro = Model::where('user_id', $id)
    ->whereNull('deleted_at')
    ->first();

if (!$registro) {
    $registro = new Model();
    $registro->user_id = $id;
}

$registro->campo1 = 'valor';
$registro->campo2 = 'valor';
$registro->save();

💡 Dica extra: proteja no banco

Mesmo com a lógica certa no código, ainda é possível cometer erros. Garanta unicidade no banco com índices condicionais:

CREATE UNIQUE INDEX idx_user_unico
ON minha_tabela (user_id)
WHERE deleted_at IS NULL;

O método updateOrCreate é poderoso, mas não foi feito para lidar com NULL em comparações de forma transparente. Use whereNull() quando necessário e, se possível, complemente com um índice único no banco de dados.