🚀 Feature Request: Add QueryFailed event for failed database queries

[vinitkadam03]

Problem

Laravel currently provides a QueryExecuted event that fires after a database query has succeeded.
However, there is no equivalent event for failed queries.

This creates a few limitations:

• If a query throws a QueryException but is caught by user code (i.e. never reaches the exception handler), there’s no way to centrally observe or log it.
• Developers who want consistent logging/monitoring must override Connection::run() or wrap drivers manually.
• Makes it harder to build clean telemetry, monitoring, and alerting integrations for database errors.

---

Proposal

Introduce a new event: Illuminate\Database\Events\QueryFailed, fired whenever a database query fails with a QueryException.

Proposed event payload:

• $sql (string): the SQL query
• $bindings (array): the bound parameters
• $connectionName (string): the connection name
• $exception (QueryException): the exception object

---

Example Usage

use Illuminate\Database\Events\QueryFailed;

Event::listen(QueryFailed::class, function (QueryFailed $event) {
    Log::error('DB query failed', [
        'sql'        => $event->sql,
        'bindings'   => $event->bindings,
        'connection' => $event->connectionName,
        'error'      => $event->exception->getMessage(),
    ]);
});

---

Implementation Sketch

New Event Class

namespace Illuminate\Database\Events;

use Illuminate\Database\QueryException;

class QueryFailed
{
    public function __construct(
        public string $sql,
        public array $bindings,
        public string $connectionName,
        public QueryException $exception,
    ) {}
}

---

Benefits

• Unified way to track both successful (QueryExecuted) and failed (QueryFailed) queries.
• Enables clean logging, telemetry, metrics, and alerting without custom hacks.
• Keeps developer experience consistent and expressive.

---

Considerations

• Slight overhead: dispatching an event on failure (but failures are rare relative to successes).
• Needs to work consistently across all drivers (MySQL, Postgres, SQLite, SQL Server).

---

💡 This would align well with Laravel’s existing event system and make DB monitoring more robust out of the box.

[macropay-solutions]

@vinitkadam03
Basically this is all you need

The query exception has the connection name, query and bindings

<?php

namespace Illuminate\Database\Events;

use Illuminate\Database\QueryException;

class QueryFailed
{
    public function __construct(
        public QueryException $queryException
    ) {
    }
}

Can this be considered a breaking change?

Yes because the objects are passes with memory address and any change to them is persisted.

[vinitkadam03]

Thanks for raising this. This may not be a breaking change since it only introduces a new event and doesn’t modify existing contracts or behavior.

It’s true that objects in PHP are reference types, so listeners could technically mutate the QueryException instance. However, that’s already the case with other framework events (for example, QueryExecuted exposes the live connection and bindings), and by convention event listeners are expected to be consumers rather than mutators.

If immutability becomes a concern, we could consider passing only the relevant scalar data (sql, bindings, connectionName) instead of the raw exception, but I think exposing the full exception gives developers more context while staying consistent with other events.

[macropay-solutions]

How about this

<?php

namespace Illuminate\Database\Events;

class QueryFailed
{
    public function __construct(
        public string $queryExceptionFqn,
        public ?string $connectionName,
        public string $sql,
        public array $bindings,
        public \Throwable $previous,
        public string $message
    ) {
    }
}

Enforcing immutability on any event will break the updating event from being used for additional changes to the model for example. All it remains here is to choose between these proposals or to come up with a new one.

[macropay-solutions]

@vinitkadam03 bear in mind that insertOrIgnore and such will trigger this event leading to false positives. Also lost connection might mess things up (tryAgainIfCausedByLostConnection method). Because of this, this idea does not seem so good...

[Sophist-UK]

I am unclear why the exception should be immutable - perhaps someone would want to write an event handler which would mutate it. (Event handlers are often used for logging and other asynchronous events that don't change anything, but there is no reason why they cannot be synchronous and make changes.)

However, if you are going to allow the variable holding the exception to be mutable, then (because PHP variables are untyped) then perhaps you need to ensure that the variable after the event is still holding a throwable object.

I would also suggest (not sure though) that the object after the event should have to be one of the existing exception types - would you really want an unknown exception type to be thrown by this code?

So IMO you either need to:

1. Leave the exception mutable without checks in case the developer wants to mutate it, and the developer will have to hope that someone else hasn't coded an event handler that will screw up the exception (as proposed).
2. Leave the exception mutable and add a complete set of checks to avoid someone screwing up the exception..
3. Make the exception immutable by the event handler by passing the event handler the information that the exception would contain without passing the actual exception (as proposed)
4. Make the exception immutable by the event handler by passing a cloned copy of the exception to the event handler.

All of these have their potential wrinkles that could cause confusion. My suggestion would be to keep it as simple as possible i.e. the first proposed code above leaving the exception mutable.

[macropay-solutions]

@Sophist-UK how about the false positives? What do you think?

PS. an exception can't be cloned via __clone(). You have to recreate it as a "clone".