Weave Code
Laravel Sql Commenter Laravel Package
spatie/laravel-sql-commenter
Adds sqlcommenter-style comments to Laravel database queries, embedding context like controller and action. Makes it easy to trace slow or problematic SQL back to the exact code path, and works with tools like PlanetScale Query Insights.
Add comments to SQL queries made by Laravel
Frequently asked questions about Laravel Sql Commenter
- How do I add custom comments to SQL queries in Laravel using this package?
- Use `SqlCommenter::addComment()` in your `AppServiceProvider` or middleware. For example, `SqlCommenter::addComment('controller={controller},action={action}')` injects dynamic metadata. You can also pass static strings or request-specific data like `request()->header('X-Request-ID')`.
- Does this package work with raw PDO queries or only Eloquent/Query Builder?
- It primarily works with Eloquent and Query Builder queries. Raw PDO queries bypass Laravel’s query hooks, so you’ll need to wrap them manually or use middleware to annotate them. Test edge cases like `DB::raw()` or dynamic SQL strings in your application.
- Will this package slow down my Laravel application in production?
- The overhead is minimal (~1–5ms per query), but benchmark high-traffic endpoints in staging. Disable comments in production if they’re not critical for observability, or use middleware to conditionally enable them (e.g., only for admin routes).
- Can I integrate this with Laravel Debugbar or other query logging tools?
- Yes, the package is non-invasive and works alongside Debugbar or Sentry. Comments appear in raw SQL logs, so tools parsing those logs (like Debugbar) will automatically include them. Ensure no duplicate SQL modifications exist in other packages using the same query hooks.
- What Laravel versions does this package support, and how do I check compatibility?
- It supports Laravel 8+ and is tested up to Laravel 11.x. Check the [Packagist page](https://packagist.org/packages/spatie/laravel-sql-commenter) for the latest version and Laravel version constraints. For LTS stability, target the highest supported Laravel minor version.
- How do I add request IDs or user-specific metadata to SQL comments?
- Use middleware to dynamically inject data before queries run. For example, in middleware: `SqlCommenter::addComment('request_id=' . request()->header('X-Request-ID') . ',user_id=' . auth()->id())`. This ensures every query includes traceable context.
- Are there conflicts with other packages that modify SQL queries (e.g., query loggers)?
- Potential conflicts arise if other packages modify the same query hooks (e.g., `DB::listen`). Test for precedence issues by running queries with both packages enabled. If conflicts occur, use middleware-based injection instead of query builder macros for more predictable behavior.
- Does this package work with databases other than MySQL or PostgreSQL?
- It supports MySQL, PostgreSQL, and SQLite out of the box. For Oracle or SQL Server, you may need to adjust the SQL comment syntax or disable comments if the database doesn’t support inline comments. Test thoroughly with your target database.
- How can I verify SQL comments are working in all query paths (Eloquent, Query Builder, raw SQL)?
- Log raw SQL queries (e.g., via `DB::listen`) or use a tool like PlanetScale’s Query Insights to confirm comments appear. Test critical paths: Eloquent models, Query Builder queries, and raw SQL wrappers. Add assertions in PHPUnit to validate comment presence in CI.
- What’s the best way to roll this out in a production Laravel application?
- Start with a pilot: install the package, configure comments for a single high-traffic endpoint, and monitor performance/logs. Gradually expand to include request IDs or feature flags. Exclude sensitive data (e.g., passwords) from comments, and document the format for support teams.
Weaver
How can I help you explore Laravel packages today?