Pandatech.SharedKernel.Postgres 2.1.0

Pandatech.SharedKernel.Postgres

PostgreSQL integration helpers for ASP.NET Core 10. Wraps Npgsql, Entity Framework Core, health checks, exception mapping, query locks, snake_case naming, and audit trail wiring into a small set of extension methods so every service starts from the same consistent baseline.

Requires .NET 10.0. Uses C# 14 extension members and cannot be downgraded.

Table of Contents

1. Installation
2. What is included
3. Registering a DbContext
4. Migrations
5. Model configuration helpers
6. Health checks

Installation

dotnet add package Pandatech.SharedKernel.Postgres

What is included

Every AddPostgresContext* overload automatically applies the following to your DbContext:

Registering a DbContext

All overloads are on WebApplicationBuilder and return WebApplicationBuilder for chaining. Every variant automatically registers a Postgres health check named postgres_{DatabaseName}.

Basic registration (no pooling, no audit trail)

// Minimal — connection string only
builder.AddPostgresContext<AppDbContext>(connectionString);

// With migrations assembly by name
builder.AddPostgresContext<AppDbContext>(connectionString, "MyApp.Migrations");

// With migrations assembly by Assembly reference
builder.AddPostgresContext<AppDbContext>(connectionString, typeof(Program).Assembly);

// With migrations assembly by marker type
builder.AddPostgresContext<AppDbContext, Program>(connectionString);

// Full control via NpgsqlDbContextOptionsBuilder callback
builder.AddPostgresContext<AppDbContext>(connectionString, npgsql =>
{
    npgsql.MigrationsAssembly("MyApp.Migrations");
    npgsql.CommandTimeout(60);
});

With connection pooling

Same set of overloads, prefixed with Pool:

builder.AddPostgresContextPool<AppDbContext>(connectionString);
builder.AddPostgresContextPool<AppDbContext>(connectionString, "MyApp.Migrations");
builder.AddPostgresContextPool<AppDbContext, Program>(connectionString);
builder.AddPostgresContextPool<AppDbContext>(connectionString, npgsql => { ... });

Use pooling for high-throughput services. Note that DbContext pooling requires that your context has no scoped dependencies injected via the constructor; use service provider overloads ((sp, options) => ...) for those cases.

With audit trail (no pooling)

Registers the Pandatech.EFCore.Audit interceptors alongside the standard options:

builder.AddPostgresContextWithAuditTrail<AppDbContext>(connectionString);
builder.AddPostgresContextWithAuditTrail<AppDbContext>(connectionString, "MyApp.Migrations");
builder.AddPostgresContextWithAuditTrail<AppDbContext, Program>(connectionString);
builder.AddPostgresContextWithAuditTrail<AppDbContext>(connectionString, npgsql => { ... });

With pooling and audit trail

builder.AddPostgresContextPoolWithAuditTrail<AppDbContext>(connectionString);
builder.AddPostgresContextPoolWithAuditTrail<AppDbContext>(connectionString, "MyApp.Migrations");
builder.AddPostgresContextPoolWithAuditTrail<AppDbContext, Program>(connectionString);
builder.AddPostgresContextPoolWithAuditTrail<AppDbContext>(connectionString, npgsql => { ... });

Migrations

Apply pending migrations at startup:

// Synchronous
app.MigrateDatabase<AppDbContext>();

// Asynchronous
await app.MigrateDatabaseAsync<AppDbContext>(ct);

Both create a scoped service provider, resolve the context, and call Database.Migrate / Database.MigrateAsync. Place these calls after app.Build() and before app.Run().

Model configuration helpers

Add to ConfigureConventions and OnModelCreating in your DbContext:

protected override void ConfigureConventions(ModelConfigurationBuilder builder)
{
    // Map all decimal properties to NUMERIC(40, 20) — prevents precision loss
    builder.ConfigureDecimalType();
}

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    // Set all foreign key delete behavior to Restrict (no accidental cascades)
    modelBuilder.RestrictFkDeleteBehaviorByDefault();
}

ConfigureDecimalType sets precision (40, 20) globally. Override individual properties via [Precision] or fluent API if you need a narrower type for a specific column.

RestrictFkDeleteBehaviorByDefault iterates all foreign keys at model build time and sets DeleteBehavior.Restrict. Override individual relationships fluently after this call if cascade delete is intentionally needed.

Health checks

The health check is registered automatically by every AddPostgresContext* overload. It uses AspNetCore.HealthChecks.NpgSql with a 5-second timeout and is named postgres_{DatabaseName} where the database name is parsed from the connection string.

To expose the health check endpoint, use MapHealthCheckEndpoints() from Pandatech.SharedKernel:

app.MapHealthCheckEndpoints(); // /above-board/health

Or register your own endpoint:

app.MapHealthChecks("/health");

If the database name cannot be parsed from the connection string, registration throws ArgumentException at startup rather than silently registering a misnamed check.

License

MIT