Getting started
This section covers installing JauntyQ, the requirements it has on your project, and the minimum wiring to get generated code out of a build. Once you are set up, work through the first-hour tutorial and the feature guides.
Requirements
- .NET SDK 8.0 or later. The generator is a Roslyn incremental source generator and runs inside the compiler; your project targets any framework Roslyn supports (net8.0+ recommended).
- A database provider package appropriate to your dialect, referenced by
the consuming project, JauntyQ emits ADO.NET calls but does not bundle a
driver:
- SQL Server / Azure SQL:
Microsoft.Data.SqlClient - PostgreSQL:
Npgsql - MySQL / MariaDB:
MySqlConnector - SQLite:
Microsoft.Data.Sqlite
- SQL Server / Azure SQL:
- A schema source, either a committed
.schema.jsonsnapshot pulled with thejauntyqCLI, or checked-in DDL (see DDL as schema source).
The Extrode.JauntyQ.Runtime package is IsAotCompatible; the generated code uses no
reflection and no runtime SQL parsing, so it is Native AOT and trim compatible
provided your database provider is too.
Install the packages
The core packages are on NuGet.org. Reference both:
<ItemGroup>
<PackageReference Include="Extrode.JauntyQ.Generator" Version="0.6.1" PrivateAssets="all" />
<PackageReference Include="Extrode.JauntyQ.Runtime" Version="0.6.1" />
</ItemGroup>
Extrode.JauntyQ.Generator installs as a Roslyn analyzer automatically; the package
ships the MSBuild props that register JauntyQDialect and JauntyQAutoCrud,
so no OutputItemType="Analyzer" or <CompilerVisibleProperty> entries are
needed when consuming the package. Extrode.JauntyQ.Runtime carries the handful of
types the generated code depends on and must be a normal (non-private)
reference.
Consuming from source (in-repo)
If you build against the repository directly rather than the package, reference the projects instead, the generator as an analyzer, the runtime as a normal reference:
<ItemGroup>
<ProjectReference Include="..\Extrode.JauntyQ.Generator\Extrode.JauntyQ.Generator.csproj"
OutputItemType="Analyzer"
ReferenceOutputAssembly="false" />
<ProjectReference Include="..\Extrode.JauntyQ.Runtime\Extrode.JauntyQ.Runtime.csproj" />
</ItemGroup>
Point the generator at your files
The generator reads your SQL and schema through MSBuild AdditionalFiles. The
standard glob picks up every .sql file under db/ (queries, migrations, and
DDL alike, they are classified by folder) plus the snapshot:
<ItemGroup>
<AdditionalFiles Include="db\**\*.sql" />
<AdditionalFiles Include="db\schema\*.schema.json" />
</ItemGroup>
The full set of properties, globs, and folder conventions is in the configuration reference.
The db/ folder layout
db/
schema/
jaunty.schema.json committed snapshot (authoritative schema source)
tables/
Products/
GetById.sql one file per query; file name = method name
GetByCategory.sql
migrations/
0001_add_column.sql pending DDL, applied on top of the snapshot
Folder name under tables/ = entity name = generated accessor class
(db.Products). File name (without .sql) = method name. Auto-CRUD methods
(GetAll, GetById, Insert, Update, Delete, Upsert, BulkInsert) are
synthesised for every table unless a same-named .sql file overrides them.
First build
Pull a snapshot (see the CLI reference). The CLI ships as a .NET global tool,
dotnet tool install --global Extrode.JauntyQ.Cliinstalls it asjauntyq(the premium verbs come withExtrode.JauntyQ.Cli.Premium, same command). Working inside a clone of this repository, the equivalent without installing is:bashdotnet run --project src/Extrode.JauntyQ.Cli -f net8.0 -- schema pull --provider sqlserver \ --connection-env MYDB_CONN \ --output db/schema/jaunty.schema.jsonAdd a query file, e.g.
db/tables/Products/GetById.sql:SQL-- @first SELECT ProductId, ProductName, UnitPrice FROM Products WHERE ProductId = @ProductIdBuild. Then use the generated surface:
C#using var conn = new SqlConnection(connectionString); var db = new JauntyDb(conn); Product? p = db.Products.GetById(42);
If a query does not match the schema, the build fails with a JNTxxxx
diagnostic rather than compiling. If something does not generate as expected,
see troubleshooting.