QueryLens 1.1.1

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:

• wrap each statement in 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

Mark your SQL constants with the appropriate attribute, then validate the whole assembly in a single assertion.

public static class OrderQueries
{
    [SqlQuery]
    public static readonly string GetById = "SELECT id, total FROM orders WHERE id = @Id";

    [SqlInsert]
    public static readonly string Create = "INSERT INTO orders (id, total) VALUES (@Id, @Total)";

    [SqlUpdate]
    public static readonly string UpdateTotal = "UPDATE orders SET total = @Total WHERE id = @Id";

    [SqlDelete]
    public static readonly string Remove = "DELETE FROM orders WHERE id = @Id";
}

Then in your test project:

QueryLens.Dialect = DialectProfile.SqlServer2017;

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

Assert.True(result.AllValid);

ValidateAssembly discovers every field, property, and method decorated with a [SqlQuery], [SqlInsert], [SqlUpdate], [SqlDelete], [SqlMerge], or [SqlStoredProc] attribute and validates each one against the active 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

Documentation

• Interface contracts
• Settings explained
• Testing patterns

License

MIT