Lib.Db is a SQL Server data access library for .NET applications that prefer stored procedures, typed results, conservative SQL defaults, and explicit runtime configuration.

The README is the current-user entry point. Release history, verification details, and security notes live in the linked docs so this page stays short enough to scan during implementation.

Install the Lib.Db package through your normal NuGet workflow.

<ItemGroup>
  <PackageReference Include="Lib.Db" Version="x.y.z" />
</ItemGroup>

Pin the package version in the application or through central package management. Do not commit real connection strings, tokens, or credentials. Use redacted placeholders in samples.

Keep connection string values in user secrets, environment variables, deployment configuration, or another untracked local source.

{
  "ConnectionStrings": {
    "Default": "<provided outside source control>"
  },
  "LibDb": {
    "ConnectionStringNames": ["Default"],
    "ConnectionSecurityProfile": "Production",
    "RawSqlPolicy": "DenyWriteText",
    "Mars": "ForceEnable",
    "EnableSchemaCaching": true,
    "EnableResilience": true,
    "EnableObservability": false
  }
}

Register Lib.Db once during application startup.

using Microsoft.Extensions.Hosting;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);
builder.Services.AddLibDb(builder.Configuration);

IHost app = builder.Build();
await app.RunAsync();

Use IDbSession to select a configured database, call a stored procedure, pass parameters, and read a DbResult<T>.

using Lib.Db.Contracts.Core;
using Lib.Db.Contracts.Entry;

public sealed class UserRepository(IDbSession session)
{
    public sealed record User(int Id, string Name, string Email);

    public async Task<User?> GetUserAsync(int id, CancellationToken ct)
    {
        DbResult<User?> result = await session.Default
            .Procedure("dbo.usp_GetUser")
            .With(new { Id = id })
            .QuerySingleAsync<User>(ct);

        return result.IsSuccess ? result.Value : null;
    }

    public async Task<int> RegisterAsync(string name, string email, CancellationToken ct)
    {
        DbResult<int?> result = await session.Default
            .Procedure("dbo.usp_RegisterUser")
            .With(new { Name = name, Email = email })
            .ExecuteScalarAsync<int>(ct);

        return result.IsSuccess ? result.Value ?? 0 : -1;
    }
}

Runtime TVP support lets a stored procedure receive scalar parameters and table-valued parameters in the same parameter object.

DbResult<int> result = await session.Default
    .Procedure("dbo.usp_UpsertProducts")
    .With(new
    {
        RequestedBy = userId,
        Products = LibDb.Tvp("dbo.T_Product", products)
    })
    .ExecuteAsync(ct);

The SQL principal that executes a TVP procedure needs EXECUTE permission on the routine and REFERENCES permission on the user-defined table type, its schema, or its database.

For repeated calls or Native AOT targets, register a static shape at startup.

using System.Data;

builder.Services.AddLibDb(options =>
{
    options.Tvp.Map<ProductRow>("dbo.T_Product")
        .Column("ProductId", SqlDbType.Int, static row => row.ProductId)
        .Column("Name", SqlDbType.NVarChar, static row => row.Name, size: 100)
        .Column("Price", SqlDbType.Decimal, static row => row.Price, precision: 18, scale: 2);
});

See Configuration for setup-oriented options and Advanced Features for schema-adaptive descriptors, cache flush behavior, AOT guidance, and TVP versus bulk insert tradeoffs.

• Guide introduces setup, configuration, and day-to-day usage.
• Configuration covers stable setup and option entry points.
• Advanced Features covers Runtime TVP, AOT, resilience, caching, JSON mapping, bulk insert, and pool metrics.
• API Reference lists the public API surface and extension points.
• Operations covers production configuration and operational guardrails.
• Fluent API Reference documents the staged procedure call API.
• Cookbook provides task-focused examples.
• History contains release notes and migration history.

MIT License