Quarry 0.4.0

Quarry

Type-safe SQL builder for .NET 10. Source generators + C# 12 interceptors emit all SQL at compile time. AOT compatible. Zero runtime dependencies. Structured logging via Logsmith Abstraction mode.

Documentation | API Reference | Benchmark Dashboard

Packages

Name	NuGet	Description
Quarry		Runtime types: builders, schema DSL, dialects, executors.
Quarry.Generator		Roslyn incremental source generator + interceptor emitter.
Quarry.Analyzers		Compile-time SQL query analysis rules (QRA series) with code fixes.
Quarry.Analyzers.CodeFixes		Code fix providers for QRA diagnostics.
Quarry.Migration		Cross-ORM conversion toolkit with Roslyn analyzers + code fixes for EF Core, Dapper, ADO.NET, and SqlKata (QRM series). Backs quarry convert.
Quarry.Tool		CLI tool for migrations, database scaffolding, and cross-ORM conversion (quarry command).

Why Quarry Exists

In most .NET data access libraries, SQL is built at runtime. LINQ expressions are translated on every call, column mapping relies on reflection, and query errors only surface when the code executes. This makes runtime performance harder to predict and rules out scenarios like NativeAOT where reflection is restricted.

Quarry is a compile-time SQL builder — not an ORM. A Roslyn incremental source generator analyzes your C# query expressions at build time and emits pre-built SQL as string literals — no runtime translation, no reflection, no fallback. Queries that can't be statically analyzed produce a compile error, not a runtime surprise.

Comparison with Other Approaches

Performance

Quarry approaches raw ADO.NET throughput with near-zero framework overhead — faster than Dapper and significantly faster than EF Core or SqlKata. This is possible because the compile-time architecture eliminates entire categories of runtime work:

• Pre-built SQL string literals — no runtime translation or expression tree walking
• Ordinal-based readers — no reflection or column-name lookups
• Carrier dispatch — zero-allocation query execution via generated carrier classes
• No runtime dependencies — nothing to initialize or warm up

Benchmarks are run against Raw ADO.NET, Dapper, EF Core, and SqlKata using BenchmarkDotNet on an in-memory SQLite database. See the live benchmark dashboard for run-over-run trends with per-commit reports and the benchmark methodology for category descriptions and how to run locally.

Features

• Compile-time SQL generation — all SQL emitted as string literals at build time; no runtime translation
• Carrier-only architecture — generated carrier classes hold pre-built SQL, parameters, and conditional dispatch; non-analyzable chains are compile errors
• Execution interceptors — all terminal methods intercepted with pre-built SQL, ordinal-based readers, and pre-allocated parameter arrays
• Conditional branch support — if/else query construction emits up to 256 SQL variants dispatched by bitmask at zero runtime cost
• Prepared queries — .Prepare() on all builder types (select, join, insert, update, delete) for reusable multi-terminal execution
• Zero-allocation readers — ordinal-based Func<DbDataReader, T> delegates generated at compile time
• Multi-dialect support — SQLite, PostgreSQL, MySQL, SQL Server with correct quoting, parameters, pagination, and identity syntax
• Type-safe schema DSL — columns as expression-bodied properties; no attributes, no conventions, no runtime model building
• Navigation joins — One<T> / HasOne<T>() reverse navigation and HasManyThrough<TTarget,TJunction> many-to-many skip navigation; explicit joins up to 6 tables plus CrossJoin<T>() and FullOuterJoin<T>()
• Navigation subqueries — Any(), All(), Count(), Sum/Min/Max/Avg(selector) on Many<T> properties compile to correlated subqueries
• Set operations — Union/UnionAll/Intersect/IntersectAll/Except/ExceptAll on any query builder, cross-entity supported
• Window functions — Sql.RowNumber/Rank/DenseRank/Ntile/Lag/Lead/FirstValue/LastValue plus aggregate-OVER with fluent PartitionBy/OrderBy
• Common Table Expressions — With<TDto>(dto => …) / FromCte<TDto>(), single and multi-CTE chains, typed post-With accessors via QuarryContext<TSelf>
• Custom type mappings — TypeMapping<TClr, TDb> with optional IDialectAwareTypeMapping for dialect-specific SQL types
• Migrations — code-first migrations with bundles, seed data, views/stored procedures, squash, checksums, and runtime hooks
• Cross-ORM conversion — quarry convert --from {dapper|efcore|adonet|sqlkata} with analyzer-driven IDE code fixes (QRM001/011/021/031 diagnostic families)
• SQL manifest — opt-in per-dialect markdown documenting every generated SQL statement; zero overhead when disabled
• Scaffolding — reverse-engineer existing databases into schema classes and a context
• Query diagnostics — ToDiagnostics() surfaces SQL, parameters, variants, projection metadata, and carrier class info
• Structured logging — Logsmith Abstraction mode with categories, slow query detection, sensitive redaction, and operation correlation
• Analyzer rules — compile-time QRA diagnostics with code fixes
• Benchmarks — comprehensive BenchmarkDotNet suite comparing Quarry against Raw ADO.NET, Dapper, EF Core, and SqlKata

Installation

<PackageReference Include="Quarry" Version="*" />

Enable interceptors by adding your context's namespace to InterceptorsNamespaces in your .csproj:

<PropertyGroup>
  <InterceptorsNamespaces>$(InterceptorsNamespaces);MyApp.Data</InterceptorsNamespaces>
</PropertyGroup>

Replace MyApp.Data with the namespace containing your QuarryContext subclass. If your context has no namespace, use Quarry.Generated.

Optional: add compile-time query analysis rules:

<PackageReference Include="Quarry.Analyzers" Version="*"
    OutputItemType="Analyzer"
    ReferenceOutputAssembly="false" />

Quick Start

// 1. Define a schema
public class UserSchema : Schema
{
    public static string Table => "users";
    public Key<int> UserId => Identity();
    public Col<string> UserName => Length(100);
    public Col<string?> Email { get; }
    public Col<bool> IsActive => Default(true);
}

// 2. Define a context
[QuarryContext(Dialect = SqlDialect.SQLite)]
public partial class AppDb : QuarryContext
{
    public partial IEntityAccessor<User> Users();
}

// 3. Query
await using var db = new AppDb(connection);

var activeUsers = await db.Users()
    .Select(u => (u.UserName, u.Email))
    .Where(u => u.IsActive)
    .OrderBy(u => u.UserName)
    .Limit(10)
    .ExecuteFetchAllAsync();

The generator emits an interceptor that replaces the ExecuteFetchAllAsync call with pre-built SQL and a typed reader. No runtime translation occurs.

Samples