brakit/docs

Query Analysis

Automatic detection of N+1 queries, slow queries, and duplicate database calls.

How Queries Are Captured

Brakit instruments your database libraries via in-process hooks. The adapter system auto-detects installed libraries and patches them:

LibraryWhat's captured
pg (PostgreSQL)Every query via Client.prototype.query: SQL, duration, row count
mysql2Every query and execute call: SQL, duration, row count
PrismaEvery operation via client extensions: model, action, duration, row count

Every query is normalized to a common format: operation (SELECT, INSERT, etc.), table name, duration, row count, and correlated to the HTTP request that triggered it.

N+1 Query Detection

When the same query pattern is repeated 5 or more times within a single request, brakit flags it as an N+1 query. This is one of the most common performance issues in web applications.

For example, if you load a list of 20 posts and each one triggers a separate query to fetch its author:

SELECT * FROM posts LIMIT 20          -- 1 query
SELECT * FROM users WHERE id = 1       -- repeated
SELECT * FROM users WHERE id = 2       -- for each
SELECT * FROM users WHERE id = 3       -- post
...                                    -- 20 more times

Brakit flags the repeated SELECT * FROM users pattern and shows the count. The fix is usually to use an include or JOIN to load related data in a single query.

With Prisma, use include or select to eager-load relations instead of accessing them lazily in a loop. With raw SQL, use a JOIN or WHERE id IN (...) batch query.

Query Insights

Beyond N+1, brakit's analysis engine detects several query patterns:

  • Redundant queries: Exact same SQL fired 2+ times within one request. Usually indicates a missing cache or duplicate code path.
  • Cross-endpoint queries: Same query appearing on >50% of endpoints. May indicate a good candidate for middleware or caching.
  • Query-heavy endpoints: More than 5 queries per request on average. Often a sign of missing eager-loading.
  • SELECT * detection: Queries selecting all columns when you probably only need a few.
  • High row counts: Queries returning 100+ rows. Usually should have a LIMIT.

Slow Query Flagging

Queries that take longer than 100ms are highlighted as slow. This is a separate, stricter threshold than the slow request threshold (2s). Individual database queries should be fast even if the overall request takes longer.

Common causes of slow queries:

  • Missing database indexes
  • Full table scans (SELECT without WHERE)
  • Large result sets without LIMIT
  • Complex JOINs on unindexed columns

Duplicate Detection

Brakit detects duplicate API calls within an action. If the same endpoint is called multiple times with the same parameters, it flags the redundancy percentage. For polling requests (3+ identical calls), brakit collapses them into a single entry with a count.

Queries Tab

The Queries tab in the dashboard shows every captured database query with:

  • Operation: SELECT, INSERT, UPDATE, DELETE
  • Table: The target database table or model
  • Duration: How long the query took
  • Row Count: Number of rows affected/returned
  • Full SQL: The complete query (click to expand and copy)
  • Source: Which adapter captured it (pg, mysql2, prisma)
Previous← Security RulesNextPerformance →