Source Code Mapping

Query Doctor can link every query captured by pg_stat_statements back to the application code that produced it — the source file, line number, HTTP route, and request method. This is powered by SQLCommenter tags that your ORM appends as structured SQL comments.

How it works

An SQLCommenter-enabled ORM wraps each query in a comment containing key-value metadata:

/* file='%2Fhome%2Fuser%2Fproject%2Fsrc%2Fusers%2Fservice.ts%3A42%3A5',route='%2Fapi%2Fusers',method='GET',db_driver='drizzle' */
SELECT id, name FROM users WHERE active = true;

When Query Doctor reads pg_stat_statements, its analyzer extracts these tags and displays them all alongside the query in the Live Queries detail view. Every tag is shown as a key-value pair, but the file tag gets special treatment — when present, Query Doctor renders it as a clickable link that opens the exact file and line in your IDE (see Configuring your IDE below).

Supported tags

Tag	Description
file	Source file, line, and column (path:line:column)
func_name	Enclosing function/method — edit-stable, omitted for anonymous call sites
route	HTTP route that triggered the query
method	HTTP request method (GET, POST, etc.)
db_driver	ORM / driver identifier
Custom tags	Any arbitrary key-value pairs you attach

Trace context (OpenTelemetry span and trace IDs) is included automatically when a tracer is active.

Edit-stable source mapping with func_name

The file tag pins a query to a path:line:column captured at the analyzed revision. Line and column numbers drift as code above the call site changes, so mapping captured queries back to source against a different revision can silently misattribute them.

The func_name tag records the enclosing function or method of the call site (e.g. reactionsRepo.findFavorites). A symbol name doesn’t move when lines shift above it, so it’s a stable join key for mapping captured queries to the source methods that produced them — without checking out the exact commit the capture ran against.

The symbol comes from the same build-time stack frame as file, so it carries the same reliability envelope. Integrations capture it when present and fall back to file:line otherwise — minified or bundled production builds may mangle or drop function names, in which case the tag is omitted. (symbol is accepted as an alternate spelling.)

Enabling tags

Install a tracking integration for your database driver or ORM:

• Drizzle — @query-doctor/sqlcommenter-drizzle
• EF Core — QueryDoctor.SqlCommenter.EFCore — EF Core interceptor that appends tags via stack inspection or explicit context
• MikroORM — @query-doctor/sqlcommenter-mikroorm — uses MikroORM’s built-in onQuery hook
• Prisma — built-in comments API — Prisma 7.1+ has native SQLCommenter support via PrismaClient and @prisma/sqlcommenter-query-tags
• TypeORM — @query-doctor/sqlcommenter-typeorm — wraps your TypeORM DataSource
• node-postgres (pg) — postgres-tracked-pool — drop-in pg.Pool replacement that automatically adds file and func_name tags

Once the integration is in place, new queries that hit the database will carry the comment tags. Existing entries in pg_stat_statements won’t have them.

Reset pg_stat_statements after enabling

pg_stat_statements aggregates queries by their text. Queries that were already captured before you enabled SQLCommenter have no tags and will remain tagless — they won’t retroactively gain them.

After enabling your SQLCommenter integration, reset the statistics so that fresh, tagged queries replace the old entries:

1. Open the Live Queries page.
2. Click Reset queries in the toolbar.
3. Let your application run normally so new tagged queries accumulate.

This calls pg_stat_statements_reset() on your database. It only clears query statistics — no schema or data is affected.

Configuring your IDE

When a query has a file tag, the path is rendered as a clickable link. To have it open directly in your editor, configure the IDE selector:

1. Open the Live Queries page.
2. Click the settings icon in the toolbar.
3. Choose your Preferred IDE.
4. For JetBrains IDEs, also set the Project path (the local root of your project) so that relative paths resolve correctly.

Supported IDEs

VS Code family

• Cursor
• VS Code

Uses the vscode://file/path:line:column protocol.

JetBrains

• WebStorm
• PhpStorm
• IntelliJ IDEA
• PyCharm
• GoLand
• RubyMine
• Rider
• CLion

Uses the ide://open?file=path&line=N&column=N protocol. Requires the Project path setting so relative file paths can be resolved to absolute paths on your machine.

Further reading

• SQLCommenter for Drizzle — installation and framework middleware setup
• SQLCommenter for EF Core — EF Core interceptor setup and configuration
• SQLCommenter for MikroORM — MikroORM onQuery hook setup
• SQLCommenter for Prisma — Prisma 7.1+ native comments API setup
• SQLCommenter for TypeORM — TypeORM DataSource wrapper setup
• SQLCommenter specification