Weave Code
Eloquent Sqlcommenter Laravel Package
affordablemobiles/eloquent-sqlcommenter
Adds SQL comments to Laravel Eloquent queries, tagging each statement with request context like route, controller action, and trace IDs, so slow-query logs and database monitoring are easier to trace back to the code that ran them.
sqlcommenter support for Laravel's Eloquent ORM
Frequently asked questions about Eloquent Sqlcommenter
- How do I install affordablemobiles/eloquent-sqlcommenter in a Laravel application?
- Install it with Composer using composer require affordablemobiles/eloquent-sqlcommenter. Laravel's package auto-discovery registers the service provider, so no manual registration is normally needed. If you want to tweak the metadata sources, publish the package config file with php artisan vendor:publish and select the package's config tag. After that, run a query and check your query log or database monitor to confirm the comments appear.
- Which Laravel and PHP versions does eloquent-sqlcommenter support?
- The package targets modern Laravel releases and relies on the framework's query event and connection hooks, so it should work on any version that ships those APIs. Exact constraints are declared in the package's composer.json, so check the require block on Packagist before upgrading Laravel or PHP. If you are on a much older Laravel branch, verify the query-executed events behave the same way before relying on it in production.
- What metadata is added to each SQL comment by default?
- By default the comments carry the current route, the controller and action handling the request, and the Laravel framework version, all rendered in SQLCommenter's key='value' format. Everything is wrapped in a /* ... */ block appended to the end of the statement. That is enough to map a slow query in your database logs back to the endpoint and handler that produced it.
- Does it comment raw queries and the query builder, or only Eloquent models?
- It works transparently across Eloquent models, the query builder, and raw statements executed through the database connection. Comments are attached at the connection level rather than the model level, so DB::select, DB::statement, and fluent builder queries are tagged the same way as Eloquent ones. That makes it useful even in applications that mix ORM and hand-written SQL.
- Which database drivers can safely use SQL comments on queries?
- It is designed for comment-tolerant drivers such as MySQL, MariaDB, and PostgreSQL, where trailing block comments are ignored by the parser. Most SQL databases accept /* */ comments at the end of a statement, but you should confirm behaviour on the exact engine and version you deploy. Drivers or proxies that rewrite or fingerprint queries may strip the comments, so check your query logs to be sure they survive.
- Will the appended SQL comments break prepared statements, bindings, or query results?
- No. The comments are appended after the statement text and its bindings, so parameter binding, result sets, and query semantics are unchanged. The only observable difference is a slightly longer query string in logs and monitoring tools. Because the comment sits at the end of the statement, it does not interfere with WHERE clauses or LIMIT handling.
- Can I add my own attributes, such as a trace ID or tenant ID, to the SQL comments?
- Yes. The package exposes configurable metadata sources, so you can register your own resolvers that return extra key-value pairs. A common pattern is pulling a correlation or trace ID from a request header or a tracing library so database logs line up with your APM traces. Keep custom values short and avoid user-supplied strings that could contain comment terminators.
- How do I disable SQL commenting for specific environments or requests?
- The package supports opt-out, so you can switch it off entirely per environment in config or skip it at runtime for particular requests. Typical uses are disabling it in local development or excluding high-volume health-check and queue-worker endpoints. Since the queries are only annotated when enabled, opt-out has no residual effect on the statements that run.
- What is the performance overhead of annotating every query in production?
- The cost is small: a string is built from a few request attributes and appended before execution, with no extra round trips to the database. The larger practical effect is longer query text, which can make statements slightly less cache-friendly in some database engines. Benchmark on your own workload if you run extremely high query volumes, and use the opt-out config where overhead matters most.
- How is eloquent-sqlcommenter different from Laravel Telescope or query logging packages?
- Telescope and similar tools record queries inside your application for local debugging, whereas this package tags the SQL itself so the context travels into the database's own slow query log and monitoring stack. That means you get traceability in production systems you do not control, without shipping application logs there. The two approaches complement each other: use Telescope while developing and SQLCommenter comments for production observability.
Weaver
How can I help you explore Laravel packages today?