QueryLens 1.1.0

QueryLens

Validate raw SQL at test time, not runtime.

QueryLens gives hand-written SQL a lightweight validation surface for Dapper, ADO.NET, and query-registry style codebases. In v2, the default experience is intentionally small:

• write a SqlQuery, SqlInsert, SqlUpdate, SqlDelete, SqlMerge, or SqlStoredProc
• optionally set QueryLens.Dialect
• optionally call QueryLens.LoadDbSchemaFrom(...)
• assert IsValid, inspect Errors, Warnings, or ErrorSummary

Quick Start

dotnet add package QueryLens

Level 1: Generic syntax with no setup

var query = new SqlQuery("SELECT name FROM customers LIMIT 10");

Assert.True(query.IsValid);

Level 1 is permissive on purpose. If you do not set a dialect, QueryLens accepts common syntax forms across supported engines and only rejects SQL that is structurally broken.

Level 2: Dialect and version checks

QueryLens.Dialect = DialectProfile.SqlServer2017;

var query = new SqlQuery("SELECT STRING_AGG(name, ',') FROM departments");

Assert.True(query.IsValid);

Once a dialect is set, QueryLens adds stricter checks such as:

• built-in function validation
• version-gated function availability
• reserved-word warnings
• dialect-specific syntax behavior

Level 3: Schema-backed validation

QueryLens.Dialect = DialectProfile.SqlServer2017;
QueryLens.LoadDbSchemaFrom(connectionString);

var query = new SqlQuery("SELECT id, missing_column FROM customers");

Assert.False(query.IsValid);
Assert.Contains(query.Errors, issue => issue.Code == "QL0011");

Schema loading snapshots the database once, then validates against that immutable in-memory snapshot. QueryLens does not hit the database on each validation call.

Core API

QueryLens.Dialect = DialectProfile.SqlServer2019;
QueryLens.LoadDbSchemaFrom(connectionString);

var query = new SqlQuery("SELECT * FROM dbo.orders WHERE order_id = @Id");

var isValid = query.IsValid;
var errors = query.Errors;
var warnings = query.Warnings;
var summary = query.ErrorSummary;

Available facade members:

• QueryLens.Dialect
• QueryLens.HasLoadedSchema
• QueryLens.IsFrozen
• QueryLens.LoadDbSchemaFrom(...)
• QueryLens.LoadDbSchemaFromAsync(...)
• QueryLens.RefreshDbSchema()
• QueryLens.ClearDbSchema()
• QueryLens.Reset()
• QueryLens.ValidateAssembly(assembly)

Freeze Model

QueryLens uses global immutable runtime snapshots.

• configuration is mutable until first validation
• after first validation, QueryLens freezes
• changing Dialect, loading schema, refreshing schema, or clearing schema throws until QueryLens.Reset()

That design keeps cached validation results deterministic and safe under parallel test execution.

Assembly Validation

QueryLens.Dialect = DialectProfile.SqlServer2017;

var result = QueryLens.ValidateAssembly(typeof(OrderQueries).Assembly);

Assert.True(result.AllValid);

This validates every discovered SqlStatement in the target assembly against the active global QueryLens level.

Statement Types

All statement wrappers implicitly convert to string, so they still drop into Dapper naturally.

await connection.QueryAsync<Customer>(
    new SqlQuery("SELECT * FROM customers WHERE status = @Status"),
    new { Status = "active" });

Supported wrappers:

• SqlQuery
• SqlInsert
• SqlUpdate
• SqlDelete
• SqlMerge
• SqlStoredProc

Validation Levels

Performance Model

QueryLens is designed for test-time validation:

• statement construction is cheap
• parsing is lazy
• parsing happens only when validation is requested
• parsed output is cached
• validation results are cached
• runtime code that never touches validation pays effectively no validation cost

Compatibility

The legacy builder-first APIs are no longer part of the public package surface in v2. The migration story is facade-first, with any remaining builder infrastructure kept internal for friend-assembly tests and transitional implementation only.

For migration guidance, see docs/technical/V2-COMPATIBILITY-GUIDE.md.

Documentation

• Product direction: docs/PRD_v2.md
• Technical spec: docs/SPEC.md
• Interface contracts: docs/technical/INTERFACE-CONTRACTS.md
• Settings deep dive: docs/technical/QUERYLENS-SETTINGS-EXPLAINED.md
• Testing patterns: docs/testing/PATTERNS-BACKEND.md

License

MIT