planetscale-codebase-sqlcommenter-instrumentation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Codebase SQLCommenter instrumentation

代码库SQLCommenter工具集成

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.

检查连接到PlanetScale的应用程序代码仓库，推荐正确的SQLCommenter风格工具集成，以便PlanetScale Insights和Postgres Traffic Control能够将查询归因到应用程序代码路径。未经批准，请勿编辑文件或安装依赖。

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.

识别以下内容：

语言与框架。
ORM或查询构建器。
数据库适配器。
迁移工具。
后台任务系统。
路由框架。
部署元数据来源，如git SHA或版本ID。
现有的SQL注释、查询标记、追踪、OpenTelemetry或数据库中间件。
PlanetScale连接配置。
代码仓库是否连接到Vitess、Postgres，或两者都连接。

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
```

PlanetScale标签兼容性首选：

当Rails查询注释需要符合SQLCommenter格式以适配PlanetScale Query Insights时，使用PlanetScale提供的
```
activerecord-sql_commenter
```
。

其他选项：

若Rails内置查询日志足够且与目标数据库/Insights行为兼容，可使用该选项。
对于旧版Rails或已使用Basecamp风格ActiveRecord查询归因的项目，使用
```
marginalia
```
。
若项目已使用OpenTelemetry SQLCommenter生态系统，使用
```
sqlcommenter_rails
```
。

推荐标签：

```
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
```

首选：

使用
```
spatie/laravel-sql-commenter
```
生成兼容PlanetScale Query Insights的SQLCommenter格式注释。

推荐标签：

```
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
```

首选：

检测到Prisma时，使用Prisma官方提供的SQL注释包：

```
@prisma/sqlcommenter
```
```
@prisma/sqlcommenter-query-tags
```
```
@prisma/sqlcommenter-trace-context
```

注意：PlanetScale的Postgres查询标记文档可能显示Prisma缺乏官方SQLCommenter支持，但Prisma当前官方文档已提供原生SQLCommenter包。检测到Prisma时，优先遵循Prisma当前文档。

推荐标签：

```
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
```

使用OpenTelemetry SQLCommenter生态系统中维护且兼容的SQLCommenter兼容中间件或工具集成。

推荐标签：

```
application
```
```
service
```
```
route
```
```
controller
```
```
action
```
```
feature
```
```
release_sha
```

Kysely / Drizzle / Bun / custom query builders

Kysely / Drizzle / Bun / 自定义查询构建器

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.

若没有维护中的SQLCommenter包，建议在数据库客户端边界或查询构建器扩展层手动添加标记。

要求：

标签必须为结构化SQL注释。
标签必须插入到语句终止符之前。
标签必须能在ORM、代理和连接池的处理中保留。
值必须经过URL编码且符合SQL注释安全要求。
标签必须是低基数的。

Django / SQLAlchemy / psycopg2 / Flask / Python

Use SQLCommenter instrumentation from the OpenTelemetry SQLCommenter ecosystem where compatible.

Recommend tags:

```
application
```
```
framework
```
```
route
```
```
view
```
```
job
```
```
release_sha
```

使用OpenTelemetry SQLCommenter生态系统中兼容的SQLCommenter工具集成。

推荐标签：

```
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
```

使用兼容Hibernate/Spring的SQLCommenter工具集成。

推荐标签：

```
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
```

使用SQLCommenter兼容工具集成或在查询边界添加数据库包装器。

推荐标签：

```
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.

为所有框架推荐以下基线要求：

仅使用稳定、有界的值。
标记前先标准化路由。
包含应用/服务/任务归因信息。
包含部署SHA值。
包含代理、脚本、BI、工作器和集成的来源类型。
请勿包含密钥、PII、用户ID、请求ID、原始租户ID或原始URL。

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.

在推荐合并前：

确认生成的SQL注释出现在本地/预发布环境的查询日志中。
确认注释能在ORM、驱动、连接池和PlanetScale连接路径中保留。
确认Insights能显示标签。
确认标签基数是有界的。
确认Traffic Control能匹配Postgres的目标标签。
确认无敏感数据存在。

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.”

返回以下信息：

检测到的技术栈。
当前查询标记状态。
推荐的包或手动集成路径。
提议的标签 schema。
可能修改的文件。
验证步骤。
风险点。
需要批准的提议变更。

结尾需包含：

“未修改任何代码仓库文件或依赖。”