PauloRB.dev

Laravel: Como visualizar a SQL com os valores preenchidos para facilitar o debug

Por Paulo RB em 08/07/2025

No dia a dia do desenvolvimento com Laravel, é comum precisarmos inspecionar uma query SQL gerada dinamicamente. A primeira ferramenta que muitos desenvolvedores usam é:

$query->toSql();

Porém, esse método não exibe os valores reais que serão enviados ao banco de dados. Em vez disso, mostra apenas a SQL com placeholders ?, o que pode dificultar o debug, principalmente em queries complexas.

Neste artigo, vou te mostrar como criar um helper simples para resolver isso, exibindo a SQL com os valores reais preenchidos, de forma segura e prática para uso em desenvolvimento.

O problema: SQL sem valores

Vamos supor que temos o seguinte código:

$query = DB::table('users')
    ->where('name', 'João')
    ->where('age', '>=', 30);

dd($query->toSql());

A saída será:

select * from users where name = ? and age >= ?

E os valores reais estão em:

$query->getBindings(); // ['João', 30]

Mas, e se quisermos ver a query completa com os valores aplicados?

Criando um helper debug_sql

Vamos montar um helper que junta os valores aos ? da query de forma segura e prática, ideal para debug.

Arquivo: app/Helpers/debug_sql_helper.php

<?php

if (!function_exists('debug_sql')) {
    /**
     * Exibe a SQL com os bindings substituídos (somente para debug).
     *
     * @param \Illuminate\Database\Query\Builder|\Illuminate\Database\Eloquent\Builder $query
     * @param bool $return Se true, retorna a SQL em vez de dar dd().
     * @return string|void
     */
    function debug_sql($query, $return = false)
    {
        $sql = $query->toSql();
        $bindings = $query->getBindings();

        foreach ($bindings as $binding) {
            $binding = is_numeric($binding) ? $binding : "'" . addslashes($binding) . "'";
            $sql = preg_replace('/\?/', $binding, $sql, 1);
        }

        if ($return) {
            return $sql;
        }

        dd($sql);
    }
}

Ativando o helper no projeto

Para que o Laravel carregue esse helper automaticamente, adicione o caminho no composer.json:

"autoload": {
    "files": [
        "app/Helpers/debug_sql_helper.php"
    ]
}

E depois execute:

composer dump-autoload

Como usar o debug_sql

Agora você pode usar assim:

$query = DB::table('users')
    ->where('email', 'like', '%@example.com')
    ->where('status', 'active');

debug_sql($query); // Mostra a SQL com os valores reais

A saída será:

select * from users where email like '%@example.com' and status = 'active'

Você também pode obter a SQL como string, útil para logs ou testes:

$sql = debug_sql($query, true);
Log::info("SQL gerada: $sql");

Cuidados importantes

• Não use esse helper em produção, pois ele apenas simula a substituição dos parâmetros e não oferece proteção contra SQL Injection. É uma ferramenta de desenvolvimento.

• Esse método não executa a query, apenas exibe como ela seria enviada ao banco.

• Não serve para queries com binding nomeado (:param), apenas as do tipo ?.

Ferramentas simples como essa podem economizar muito tempo de debug, principalmente quando estamos lidando com queries complexas, filtros dinâmicos e comportamento inesperado no banco de dados.

Se você trabalha com Laravel no dia a dia, recomendo adicionar esse helper no seu kit de ferramentas. E se quiser ir além, pode criar até um middleware para logar queries lentas com os valores já aplicados.