Kanject.Core.SqlDatabase.Abstractions 1.3.1

Kanject.Core.SqlDatabase.Abstractions

Provider-neutral contracts for Kanject's relational data layer: ISqlEntity, ISqlRepository<TEntity>, ISqlUnitOfWork, ISqlDbContext, the SqlQuerySpec query model, and the table descriptors a provider's source generator emits. Application services depend on these interfaces; the Amazon Aurora DSQL provider implements them.

The contract is designed for Native AOT and deliberately has no EF Core, no LINQ provider and no runtime model discovery. A query is a plain object of column names, operators and values — no expression trees — and table shapes arrive as compile-time-generated descriptors instead of being reflected from your classes.

Installation

dotnet add package Kanject.Core.SqlDatabase.Abstractions

Targets .NET 8, .NET 9 and .NET 10. The package has no dependencies and is Native AOT / trimming compatible.

It contains no database driver and no in-memory implementation — pair it with a provider (see Related packages; providers are commercially licensed).

Quick start

ISqlEntity is a marker with no members; the provider's attributes declare the primary key.

using Kanject.Core.SqlDatabase.Abstractions.Interfaces;

public sealed class Customer : ISqlEntity
{
    public Guid CustomerId { get; init; }
    public string Email { get; set; } = string.Empty;
    public string Status { get; set; } = "active";
    public DateTime CreatedAt { get; set; }
}

Code application services against ISqlRepository<TEntity>:

using Kanject.Core.SqlDatabase.Abstractions.Enums;
using Kanject.Core.SqlDatabase.Abstractions.Interfaces;
using Kanject.Core.SqlDatabase.Abstractions.Models;

public sealed class CustomerService(ISqlRepository<Customer> customers)
{
    public Task<Customer?> FindByEmailAsync(string email)
    {
        var spec = new SqlQuerySpec();
        spec.Filters.Add(new SqlFilter("email", SqlOperator.Equal, email));
        return customers.GetSingleAsync(spec);
    }

    public Task<IList<Customer>> ActivePageAsync(int pageIndex, int pageSize)
    {
        var spec = new SqlQuerySpec { ResultLimit = pageSize, ResultOffset = pageIndex * pageSize };
        spec.Filters.Add(new SqlFilter("status", SqlOperator.Equal, "active"));
        spec.OrderBy.Add(new SqlOrderBy("created_at", SqlOrderDirection.Descending));
        return customers.GetAllAsync(spec);
    }

    public Task<long> CountActiveAsync()
    {
        var spec = new SqlQuerySpec();
        spec.Filters.Add(new SqlFilter("status", SqlOperator.Equal, "active"));
        return customers.CountAsync(spec);
    }

    public Task SaveAsync(Customer customer) => customers.AddOrUpdateAsync(customer);
}

Column names in a spec are SQL column names, not C# property names. The DSQL provider maps properties to snake_case by default (CreatedAt → created_at) unless a [Column] attribute overrides it.

With the DSQL provider, the entity implements IDsqlEntity (which extends ISqlEntity) and marks its key with [PrimaryKey]. The provider's AddDbContext<TContext>() registers the unit of work against ISqlUnitOfWork, and AddDsqlRepository<TRepository, TEntity>() registers each generated repository against ISqlRepository<TEntity>, so the service above resolves unchanged.

Repository operations

Every *RangeAsync method also has a CancellationToken overload whose default implementation forwards to the token-less one.

The raw SqlQueryAsync<TData> is only AOT-safe when the projection type has a generator-emitted mapper; otherwise it falls back to driver-default mapping.

Building query specs

SqlQuerySpec holds KeyPredicates, Filters, OrderBy, ExistsPredicates, ResultLimit and ResultOffset. You can fill it directly (as above) or through SqlQuerySpecOption<TEntity>, whose Config property is the spec:

using Kanject.Core.SqlDatabase.Abstractions.Extensions;

var option = new SqlQuerySpecOption<Customer>().Limit(20).Offset(40);
option.Config.Filters.Add(new SqlFilter("email", SqlOperator.ILike, "%@example.com"));

IList<Customer> page = await customers.GetAllAsync(option.Config);

Providers with a source generator emit typed per-column extensions on SqlQuerySpecOption<TEntity> — Where{Column}, OrderBy{Column} and friends in the DSQL provider. DbFunc builds the (SqlOperator, value) tuples those extensions accept:

using Kanject.Core.SqlDatabase.Abstractions.Helpers;

// WhereCreatedAt / WhereStatus are generated for the entity by the DSQL annotations package.
var since = DateTime.UtcNow.AddDays(-30);
option.WhereCreatedAt(DbFunc.GreaterThanOrEqual(since))
      .WhereStatus(DbFunc.In("active", "trial"));

DbFunc covers Equal, NotEqual, LessThan, LessThanOrEqual, GreaterThan, GreaterThanOrEqual, Like, ILike, In, NotIn and Between. SqlOperator additionally has IsNull and IsNotNull.

Units of work

ISqlUnitOfWork resolves repositories and scopes a transaction:

// Account is an ISqlEntity like Customer above.
public sealed class TransferService(ISqlUnitOfWork unitOfWork)
{
    public async Task MoveAsync(Account from, Account to, CancellationToken cancellationToken)
    {
        var accounts = unitOfWork.Repository<Account>();

        unitOfWork.BeginTransaction();
        await accounts.UpdateAsync(from);
        await accounts.UpdateAsync(to);
        await unitOfWork.CommitAsync(cancellationToken);
    }
}

The contract leaves it to the implementation whether BeginTransaction/CommitAsync open a real database transaction. The DSQL provider does: it issues BEGIN on a dedicated connection that every repository call in the same scope enlists in, COMMIT on CommitAsync, and rolls back if the unit of work is disposed without committing. It registers the unit of work as scoped, and its own unit-of-work interface adds BeginTransactionAsync and RollbackAsync.

Schema descriptors

ISqlDbContext exposes the default Schema and GetTableDescriptors(). A provider's source generator emits one SqlTableDescriptor per repository-bound entity — Schema, Table, PrimaryKey (SqlPrimaryKey), Columns (SqlColumnDescriptor: name, database type, nullability) and Indexes (SqlIndexDescriptor). A provider's schema applier creates missing schemas, tables and indexes from that list (the DSQL provider does so at startup when its schema check is enabled). Nothing inspects your entity classes at runtime.

Public surface at a glance

Related packages

License

Licensed under the Kanject Code Libraries License Agreement (KCLLA); the full text ships in this package as LICENSE.md. Organizations whose trailing-twelve-month gross revenue and total funding raised are each below US$250,000 may use it at no cost under the Free Tier. At or above either threshold a commercial license is required — contact commercial@kanjectbusiness.com.