PlanetScale query tags

Unkey annotates every MySQL statement with SQLCommenter-compatible metadata before it reaches PlanetScale. Tags show up in Query Insights so we can attribute query time to services, deploys, sqlc operations, and (for dashboard) tRPC routes.

Why

PlanetScale Query Insights groups queries by fingerprint. Without tags, hot paths like FindKeyForVerification appear as anonymous load. Tags let us answer:

Which service issued this query?
Which deploy introduced the regression?
Which sqlc operation or tRPC route drove the spike?

Keep tag cardinality low. Insights indexes tag keys; high-cardinality values (user ids, key ids) must never appear in comments. Tag values are URL-encoded per the SQLCommenter spec before they are quoted, so routes like POST /v2/keys.verifyKey serialize safely.

Tag schema

Key	Source	Example
`application`	constant	`unkey`
`service`	process name	`api`, `frontline`, `dashboard`
`region`	`UNKEY_REGION` (set in helm per cluster)	`us-east-1`
`release_sha`	link-time git SHA (7 chars)	`a1b2c3d`
`operation`	sqlc `-- name:` header (Go only)	`FindKeyForVerification`
`mode`	connection role (Go only)	`rw`, `ro`
`route`	request context	`deploy.envVars.create` (tRPC path)
`source`	request context	`http`, `restate`, `trpc`, `webhook`

We intentionally omit an environment tag. Infra labels clusters production001, canary, or legacy staging, but those labels are not injected into platform pod env vars today. Use release_sha to identify the deployed commit (goreleaser sets buildinfo.Revision on Go binaries; Vercel sets UNKEY_GIT_COMMIT_SHA / GIT_COMMIT for dashboard). Example comment appended to SQL:

SELECT ... FROM keys WHERE ... /*application='unkey',service='api',region='us-east-1',release_sha='a1b2c3d',operation='FindKeyForVerification',mode='ro'*/

Go services

Annotation happens in pkg/mysql.Replica (and the mirrored pkg/db package). sqlc call sites stay unchanged.

Pass static tags when opening the database:

tags := sqlcomment.ForService("api", cfg.Region)
database, err := db.New(db.Config{
    PrimaryDSN:  cfg.DatabasePrimary,
    ReadOnlyDSN: cfg.DatabaseReadOnly,
    Tags:        tags,
})

Optional dynamic tags via context (HTTP zen services set these automatically with zen.WithSQLComment):

ctx = sqlcomment.WithDynamic(ctx, sqlcomment.Dynamic{Route: "POST /v2/keys.verifyKey", Source: "http"})
rows, err := database.RO().QueryContext(ctx, query, args...)

zen.WithSQLComment() reads http.Request.Pattern (for example POST /v2/keys.verifyKey) and is registered in api and frontline middleware stacks. ctrl-worker wraps the Restate ingress with sqlcomment.WrapRestateInvokeHandler, tagging routes like hydra.v1.DeployService/Deploy with source=restate. sqlcomment.Static{} disables annotation (tests and dev seeds). Package reference: pkg/mysql/sqlcomment.

TypeScript apps

Dashboard and portal use Drizzle on top of createCommentedPool from @unkey/db. The pool proxy annotates query and execute on the pool and on connections from getConnection, which is what Drizzle uses inside transactions. Useful tags on the TypeScript side:

Static (per pool): service, region, release_sha
Dynamic (per request): route (tRPC procedure path) and source (trpc, webhook, etc.)

Dashboard tRPC sets route and source through runWithSqlCommentTags in the base procedure middleware. Non-tRPC entrypoints (Stripe webhooks, server actions) should wrap their handler with runWithSqlCommentTags and set source accordingly. TypeScript pools do not emit mode: mysql2 uses a single pool without the read/write split that Go services have, so a mode tag would be misleading. Static tags read UNKEY_REGION / REGION and UNKEY_GIT_COMMIT_SHA / GIT_COMMIT for release_sha.

Verification

After deploy to staging:

Open PlanetScale Query Insights for the unkey database.
Find a high-traffic fingerprint (for example FindKeyForVerification).
Confirm service, operation, and release_sha appear on sampled queries.
For dashboard traffic, confirm route tags on tRPC-backed queries.

Local unit tests:

mise exec -- rask ./pkg/mysql/sqlcomment
mise exec -- pnpm --dir=web exec vitest run internal/db/src/sqlcomment.test.ts internal/db/src/commented-pool.test.ts

Agent notes

Do not add high-cardinality values to SQL comments.
New Go services: wire sqlcomment.ForService in run.go when constructing db.Config.
New TS apps using @unkey/db: use createCommentedPool instead of mysql.createPool.
HTTP handlers that bypass tRPC can set sqlcomment.WithDynamic (Go) or runWithSqlCommentTags (TS) per request.

Infra

Runbooks

ClickHouse

PlanetScale query tags

Why

Tag schema

Go services

TypeScript apps

Verification

Agent notes

​Why

​Tag schema

​Go services

​TypeScript apps

​Verification

​Agent notes

Why

Tag schema

Go services

TypeScript apps

Verification

Agent notes