DKNet.AspCore.Idempotency.NpgsqlStore 10.1.19

DKNet.AspCore.Idempotency.NpgsqlStore

PostgreSQL-backed persistent store for DKNet.AspCore.Idempotency, built on the shared EF Core relational store (DKNet.AspCore.Idempotency.Relational).

✨ Why use it?

• Persistent – idempotency keys live in a Postgres IdempotencyKeys table, surviving app restarts.
• Atomic under concurrency – a unique index on the composite key serializes duplicate requests in the database itself; no application-level locking needed.
• Migrations included – ships with its own EF Core migration and applies it automatically on first use, independently per connection string.
• Multi-database ready – register the store against several Postgres databases (e.g. per tenant) from the same process; each one is prepared on its own.
• Npgsql-tuned – retry-on-failure and split-query behaviour are configured out of the box.

🚀 Quick Start

dotnet add package DKNet.AspCore.Idempotency.NpgsqlStore

using DKNet.AspCore.Idempotency;
using DKNet.AspCore.Idempotency.NpgsqlStore;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddIdempotencyWithNpgsqlStore(
    builder.Configuration.GetConnectionString("IdempotencyDb")!,
    options =>
    {
        options.Expiration = TimeSpan.FromHours(48);
        options.ConflictHandling = IdempotentConflictHandling.CachedResult;
    });

var app = builder.Build();

app.MapPost("/orders", () => Results.Ok())
    .RequiredIdempotentKey();

app.Run();

Clients send an X-Idempotency-Key header on POST /orders; a retry with the same key replays the first response instead of creating a second order.

Customisation reference

There is no PostgreSQL-specific options type. AddIdempotencyWithNpgsqlStore configures the shared IdempotencyOptions from DKNet.AspCore.Idempotency:

Values are validated eagerly at registration: an empty header key or cache prefix, a non-positive expiration, a status-code window outside 100–599 or with min above max, a null JsonSerializerOptions, a MaxIdempotencyKeyLength below 1, an empty key pattern, or a whitespace ScopeHmacSecret each throw ArgumentException immediately rather than failing at request time.

Registration entry points

Fixed by this package, not exposed as options

You provide a reachable database and a login that can create tables in it; the package creates and migrates the table on first use. Nothing sweeps expired rows — ExpiresAt is indexed so you can add your own cleanup job.

IdempotencyPostgresStore is internal, so AddIdempotentKey<IdempotencyPostgresStore>() does not compile in application code — AddIdempotencyWithNpgsqlStore(...) is the supported way in. Both methods are first-wins: a second call with a different connection string is silently a no-op.

📖 Documentation

Full guide — Postgres schema, concurrency behaviour, multi-database support, and how this store composes with the core and relational packages: DKNet.AspCore.Idempotency.NpgsqlStore.md

License

MIT — see LICENSE.