Migrating from Dapper or EF Core
JauntyQ occupies the space between Dapper (hand-written SQL, hand-written mapping) and EF Core (LINQ, change tracking, runtime SQL generation). It keeps the SQL-first control of Dapper but generates the mapping, and validates the SQL, at compile time. This guide covers what changes when you move an existing data layer over.
Mental model shift
| Dapper | EF Core | JauntyQ | |
|---|---|---|---|
| Where SQL lives | inline strings | generated from LINQ | .sql files |
| Mapping | reflection at runtime | reflection/expression trees | generated at build time |
| Schema errors surface | at runtime | at runtime (mostly) | at build time |
| Change tracking | none | yes | none |
| Runtime cost | reflection per query | high (tracking, translation) | none (typed ordinal reads) |
The core move is the same in both cases: SQL (or LINQ) that lived in C# moves
into .sql files that the generator turns into typed methods.
From Dapper
Dapper is the closer fit, you already write SQL and think in terms of parameters and result shapes.
Before (Dapper):
var product = conn.QuerySingleOrDefault<Product>(
"SELECT ProductId, ProductName, UnitPrice FROM Products WHERE ProductId = @id",
new { id = 42 });
After (JauntyQ), move the SQL into db/tables/Products/GetById.sql:
-- @first
SELECT ProductId, ProductName, UnitPrice FROM Products WHERE ProductId = @ProductId
var db = new JauntyDb(conn);
Product? product = db.Products.GetById(42);
Mapping to Product, parameter typing, and the null-when-missing shape all come
from the generator. The SQL is validated against the snapshot at build time, so
a typo in a column name breaks the build instead of throwing at runtime.
Translation notes:
QuerySingleOrDefault/QueryFirstOrDefault→-- @first(returnsRow?).Query(many rows) → default (returnsList<Row>); use-- @streamfor large sets.Execute(no result) →-- @result void(returns row count).IN (@ids)list expansion →-- @each.- Anonymous-parameter objects → named parameters (
@ProductId) become typed method arguments; declare any the parser cannot infer with-- @params. - Custom projections (joins, partial selects) → a
-- @result (...)inline shape or a named DTO. - Simple CRUD you were writing by hand → delete it; auto-CRUD synthesises
GetAll/GetById/Insert/Update/Delete/Upsert/BulkInsert.
From EF Core
The move is larger because you give up LINQ-to-SQL translation and change tracking, and gain compile-time validation and zero runtime overhead.
- LINQ queries →
.sqlfiles. Eachcontext.Products.Where(...)becomes a.sqlfile. This is the bulk of the work, but it is mechanical, and the result is SQL you can read and tune. DbContext→JauntyDb.JauntyDbis a stateless facade over aDbConnection, noOnModelCreating, no migrations engine, no tracking.newone per request.- Change tracking → explicit writes. There is no
SaveChanges().Update(poco)is a full-row update (last-writer-wins); for concurrency use a SQL Serverrowversioncolumn, which auto-CRUD turns into an optimistic token. See the API overview. - EF migrations → snapshot +
db/migrations/. JauntyQ does not run migrations against the database; it simulates pending DDL indb/migrations/on top of the snapshot so the build validates against the post-migration schema. Applying migrations to the database stays in your deploy pipeline. - Navigation properties / lazy loading → explicit FK loaders. A foreign key
in the snapshot generates
db.Orders.GetByCustomerId(...); you load related data with an explicit call, not a traversal. - Entity graphs / includes → joins in SQL. Write the join yourself and shape
the result with
-- @result.
Suggested order of migration
- Pull a snapshot with
jauntyq schema pulland commit it. - Wire the generator into the project (see getting started).
- Delete hand-written CRUD you can get from auto-CRUD; keep only custom queries.
- Port custom queries into
.sqlfiles one entity folder at a time; let the build tell you (viaJNTxxxx) where SQL and schema disagree. - Replace
DbContext/Dapper call sites withJauntyDbcalls. - Add
jauntyq schema verifyto CI to catch future drift.
What does not come along
JauntyQ deliberately omits change tracking, lazy loading, a LINQ provider, and runtime model configuration. If you depend heavily on those, read Why JauntyQ (and why not) before committing to the move.