planetscale-codebase-sqlcommenter-instrumentation

name	planetscale-codebase-sqlcommenter-instrumentation
description	Inspect an application repository connected to PlanetScale and recommend SQLCommenter-compatible query tagging packages and conventions.

Codebase SQLCommenter instrumentation

Purpose

Inspect the application repository connected to PlanetScale and recommend the correct SQLCommenter-style instrumentation so PlanetScale Insights and Postgres Traffic Control can attribute queries to application code paths. Do not edit files or install dependencies without approval.

Repository inspection

Identify:

• Language and framework.
• ORM or query builder.
• Database adapter.
• Migration tool.
• Background job system.
• Routing framework.
• Deployment metadata source, such as git SHA or release ID.
• Existing SQL comments, query tags, tracing, OpenTelemetry, or database middleware.
• PlanetScale connection configuration.
• Whether the repository connects to Vitess, Postgres, or both.

Recommended package mapping

Use the most native maintained option for the detected stack.

Ruby on Rails / ActiveRecord

Preferred for PlanetScale tag compatibility:

• activerecord-sql_commenter from PlanetScale when Rails query comments need SQLCommenter format for PlanetScale Query Insights.

Other options:

• Rails built-in query logs when sufficient and compatible with the target database/Insights behavior.
• marginalia for older Rails or when Basecamp-style ActiveRecord query attribution is already in use.
• sqlcommenter_rails where the project already uses the OpenTelemetry SQLCommenter ecosystem.

Recommend tags:

• application
• controller
• action
• job
• route
• release_sha

Laravel / PHP

Preferred:

• spatie/laravel-sql-commenter for SQLCommenter-format comments compatible with PlanetScale Query Insights.

Recommend tags:

• application
• route
• controller
• action
• job
• queue
• release_sha

Prisma / TypeScript / JavaScript

Preferred:

• Prisma’s first-party SQL comments packages when Prisma is detected:
  • @prisma/sqlcommenter
  • @prisma/sqlcommenter-query-tags
  • @prisma/sqlcommenter-trace-context

Note: PlanetScale’s Postgres query-tag docs may list Prisma as lacking official SQLCommenter support, but Prisma’s own current docs provide first-party SQLCommenter packages. Prefer current Prisma docs when Prisma is detected.

Recommend tags:

• application
• service
• route
• operation
• feature
• release_sha

Knex / Sequelize / Express / Node

Use SQLCommenter-compatible middleware or instrumentation from the OpenTelemetry SQLCommenter ecosystem where maintained and compatible.

Recommend tags:

• application
• service
• route
• controller
• action
• feature
• release_sha

Kysely / Drizzle / Bun / custom query builders

If there is no maintained SQLCommenter package, recommend manual tagging at the database client boundary or query builder extension layer.

Requirements:

• Tags must be structured SQL comments.
• Tags must be inserted before the statement terminator.
• Tags must survive ORM, proxy, and pooler behavior.
• Values must be URL encoded and safe for SQL comments.
• Tags must be low-cardinality.

Django / SQLAlchemy / psycopg2 / Flask / Python

Use SQLCommenter instrumentation from the OpenTelemetry SQLCommenter ecosystem where compatible.

Recommend tags:

• application
• framework
• route
• view
• job
• release_sha

Java / Hibernate / Spring

Use SQLCommenter-compatible instrumentation for Hibernate/Spring where compatible.

Recommend tags:

• application
• service
• controller
• action
• route
• release_sha

Go / database/sql / net/http / gorilla/mux

Use SQLCommenter-compatible instrumentation or a database wrapper at the query boundary.

Recommend tags:

• application
• service
• handler
• route
• job
• release_sha

Standard tag policy

Recommend this baseline across all frameworks:

• Stable, bounded values only.
• Normalize routes before tagging.
• Include app/service/job attribution.
• Include deploy SHA.
• Include source type for agents, scripts, BI, workers, and integrations.
• Do not include secrets, PII, user IDs, request IDs, raw tenant IDs, or raw URLs.

Validation plan

Before recommending merge:

• Confirm generated SQL comments appear in local/staging query logs.
• Confirm comments survive the ORM, driver, pooler, and PlanetScale connection path.
• Confirm Insights displays tags.
• Confirm tag cardinality is bounded.
• Confirm Traffic Control can match the intended tags for Postgres.
• Confirm no sensitive data is present.

Output

Return:

• Detected stack.
• Current query tagging state.
• Recommended package or manual instrumentation path.
• Proposed tag schema.
• Files likely to change.
• Validation steps.
• Risks.
• Proposed changes requiring approval.

End with:

“No repository files or dependencies have been changed.”