QueryWatch is a .NET library for catching database-query regressions in tests and CI before they reach production. It records executed SQL, counts queries, measures timings, exports JSON summaries, and lets you fail builds on budget violations.
Works with:
- ADO.NET
- Dapper
- EF Core
QueryWatch is designed for test-time guardrails, not production profiling dashboards.
Typical use cases:
- Catch N+1 regressions introduced by ORM changes
- Enforce per-test query-count budgets
- Fail CI when average or total SQL time drifts upward
- Export machine-readable summaries for baselines and PR reporting
- Capture parameter shape metadata without storing parameter values
| Package | Purpose |
|---|---|
KeelMatrix.QueryWatch | Core recording, assertions, JSON export, ADO.NET and Dapper wrapping |
KeelMatrix.QueryWatch.EfCore | EF Core interceptor and UseQueryWatch(...) integration |
qwatch | .NET tool for enforcing query and SQL performance budgets in CI |
Core only:
dotnet add package KeelMatrix.QueryWatchEF Core integration:
dotnet add package KeelMatrix.QueryWatch
dotnet add package KeelMatrix.QueryWatch.EfCoreOptional redaction helpers:
dotnet add package KeelMatrix.RedactionQueryWatch restores KeelMatrix.Redaction and KeelMatrix.Telemetry 0.1.0 from NuGet.org. The sample helper uses a local feed only for QueryWatch packages built from this repository.
Install the public CI tool:
dotnet tool install --global qwatch --version 0.1.0usingKeelMatrix.QueryWatch;usingKeelMatrix.QueryWatch.Assertions;usingKeelMatrix.QueryWatch.Reporting;usingQueryWatchSessionsession=new();usingvarconn=rawConnection.WithQueryWatch(session);// Run code that talks to the database.QueryWatchReportreport=session.Complete();report.ShouldHaveExecutedAtMost(20);report.ShouldHaveMaxAverageTime(TimeSpan.FromMilliseconds(15));QueryWatchJson.ExportToFile(report,"artifacts/qwatch.report.json",sampleTop:200);The exported JSON can be consumed by the CLI in CI.
Wrap the test scope, execute the application code, and assert the query count stays below a fixed threshold.
Export a summary file during tests, then run the CLI in GitHub Actions to fail the build if query counts or timings regress.
Enable parameter-shape capture to understand whether code is issuing parameterized commands, without persisting sensitive parameter values.
Add redactors to remove secrets, GUID noise, timestamps, or tokens so CI diffs focus on structural query changes.
This repo ships three sample apps that consume local packages built from source. The helper scripts pack QueryWatch core and EF Core locally; Redaction and Telemetry restore from NuGet.org.
Build and pack the local packages used by the samples:
- PowerShell:
pwsh -NoProfile -File build/Dev-PackInstallSamples.ps1 - bash:
bash build/Dev-PackInstallSamples.sh
- PowerShell:
Run a sample:
dotnet run --project ./samples/EFCore.Sqlite/EFCore.Sqlite.csproj -c Release
Gate the generated summary with the CLI:
dotnet run --project ./tools/KeelMatrix.QueryWatch.Cli -- --input ./samples/EFCore.Sqlite/bin/Release/net8.0/artifacts/qwatch.ef.json --max-queries 50
usingKeelMatrix.QueryWatch;usingKeelMatrix.QueryWatch.EfCore;usingKeelMatrix.QueryWatch.Reporting;usingvarsession=newQueryWatchSession();varoptions=newDbContextOptionsBuilder<MyDbContext>().UseSqlite("Data Source=:memory:").UseQueryWatch(session).Options;// Run workload...varreport=session.Complete();QueryWatchJson.ExportToFile(report,"artifacts/ef.json",sampleTop:200);The EF Core interceptor records executed commands only. Use QueryWatchOptions to tune SQL text capture, sampling, and parameter-shape capture.
usingKeelMatrix.QueryWatch;usingKeelMatrix.QueryWatch.Reporting;usingvarsession=newQueryWatchSession();awaitusingvarraw=newSqliteConnection("Data Source=:memory:");awaitraw.OpenAsync();usingvarconn=raw.WithQueryWatch(session);varrows=awaitconn.QueryAsync("SELECT 1");varreport=session.Complete();QueryWatchJson.ExportToFile(report,"artifacts/dapper.json",sampleTop:200);If the underlying connection is a DbConnection, QueryWatch uses the higher-fidelity ADO.NET wrapper automatically.
usingKeelMatrix.QueryWatch;usingKeelMatrix.QueryWatch.Reporting;usingvarsession=newQueryWatchSession();awaitusingvarraw=newSqliteConnection("Data Source=:memory:");awaitraw.OpenAsync();usingvarconn=raw.WithQueryWatch(session);usingvarcmd=conn.CreateCommand();cmd.CommandText="SELECT 1";awaitcmd.ExecuteNonQueryAsync();varreport=session.Complete();QueryWatchJson.ExportToFile(report,"artifacts/ado.json",sampleTop:200);If captured SQL can include secrets, tokens, email addresses, or noisy identifiers, add KeelMatrix.Redaction and configure redactors on QueryWatchOptions.
usingKeelMatrix.QueryWatch;usingKeelMatrix.QueryWatch.Redaction;usingKeelMatrix.Redaction;varoptions=newQueryWatchOptions().UseRecommendedRedactors(includeTimestamps:false,includeIpAddresses:false,includePhone:false);At test time, enforce budgets directly on QueryWatchReport.
At CI time, use the CLI for:
- total-query budgets
- average-duration budgets
- total-duration budgets
- baseline comparisons
- per-pattern budgets
Per-pattern budgets support wildcards (*, ?) or a regex: prefix.
Examples:
--budget "SELECT * FROM Users*=1"
--budget "regex:^UPDATE Orders SET=3"If a summary is top-N sampled, budgets are evaluated only over those captured events. Increase sampleTop if you need stricter guarantees.
Usage:
qwatch --input file.json [options]
qwatch telemetry <status|disable|enable> [options]
Commands:
telemetry status [--json] Show effective telemetry state and repo-local config status for the current repo.
telemetry disable Write a qwatch-managed repo-local telemetry opt-out.
telemetry enable Remove or neutralize qwatch-managed repo-local telemetry opt-out.
Options:
--input <path> Input JSON summary file. (repeatable)
--max-queries N Fail if total query count exceeds N.
--max-average-ms N Fail if average duration exceeds N ms.
--max-total-ms N Fail if total duration exceeds N ms.
--baseline <path> Baseline summary JSON to compare against.
--baseline-allow-percent P Allow +P% regression vs baseline before failing.
--write-baseline Write current aggregated summary to --baseline.
--budget "<pattern>=<max>" Per-pattern query count budget. (repeatable)
Pattern supports wildcards (*, ?) or prefix with 'regex:' for raw regex.
--require-full-events Fail if input summaries are top-N sampled.
--help Show this help.
Multi-file support:
- repeat
--inputto aggregate summaries from multiple test projects - compare current results against a baseline summary
- write GitHub Actions step summaries automatically when running in CI
- inspect or manage repo-local telemetry opt-out state with
qwatch telemetry status|disable|enable
- Pattern budgets look incomplete: your summary may be sampled too aggressively. Re-export with a higher
sampleTop. - Baseline checks are noisy: use
--baseline-allow-percentand keep baselines representative. - CLI flags in the README look stale: refresh the generated block with
build/Update-ReadmeFlags.ps1. - You do not want SQL text on a hot path: set
QueryWatchOptions.CaptureSqlText = false. - You want metadata without secret leakage: use parameter-shape capture, not parameter-value capture.
QueryWatch uses KeelMatrix.Telemetry transitively for minimal anonymous usage telemetry.
See:
- PRIVACY.md for the QueryWatch-specific summary
- KeelMatrix.Telemetry README for the maintained telemetry behavior and opt-out details
For the CLI, qwatch telemetry disable writes a repo-local opt-out file and qwatch telemetry enable removes or neutralizes only qwatch-managed repo-local opt-out state. QueryWatch-owned files use managedBy: "qwatch" as the ownership marker. Higher-precedence process environment variables still win, and existing non-qwatch-managed repo-local config is left untouched.
MIT