CoreSystem.Idempotency.PostgreSql 2.0.2

⚡ CoreSystem.Idempotency.PostgreSql

PostgreSQL storage provider for CoreSystem.Idempotency, built on the IIdempotencyStorage abstraction.

It is recommended for applications that require transactional consistency and long-lived storage.

It provides a durable implementation of IIdempotencyStorage, enabling reliable persistence of idempotency entries using PostgreSQL and Dapper.

✨ Features

• ✅ Durable persistence
• ✅ PostgreSQL storage
• ✅ Dapper-based implementation
• ✅ Idempotent schema script shipped with the package
• ✅ Seamless integration with CoreSystem.Idempotency
• ✅ OpenTelemetry compatible
• ✅ Production-ready

📦 Installation

Install the framework.

dotnet add package CoreSystem.Idempotency

Install the PostgreSQL provider.

dotnet add package CoreSystem.Idempotency.PostgreSql

🚀 Quick Start

Configure PostgreSQL and register the provider.

{
  "ConnectionStrings": {
    "Idempotency": "Host=localhost;Port=5432;Database=idempotency_db;Username=admin;Password=admin"
  }
}

builder.Services
    .AddCoreIdempotency(options =>
    {
        builder.Configuration
            .GetSection("Core:Idempotency")
            .Bind(options);
    })
    .AddCoreIdempotencyPostgreSql(options =>
    {
        options.ConnectionString =
            builder.Configuration.GetConnectionString("Idempotency");
    });

PostgreSqlOptions.ConnectionString must be assigned explicitly; the provider throws at startup if it is null or empty.

Enable the middleware.

app.UseCoreIdempotency();

🗄 Database Setup

The provider does not create any schema. Apply the DDL yourself before the first request.

The database must already exist.

CREATE DATABASE idempotency_db;

Then apply the schema script shipped inside the package at scripts/postgres.sql. To extract it from the installed package, locate the package directory under ~/.nuget/packages/coresystem.idempotency.postgresql/<version>/scripts/postgres.sql.

psql -h localhost -U admin -d idempotency_db -f scripts/postgres.sql

CREATE TABLE IF NOT EXISTS idempotency_keys
(
    key TEXT PRIMARY KEY,

    state TEXT NOT NULL DEFAULT 'completed' CHECK (state IN ('in_progress', 'completed')),

    lease_id TEXT,

    request_fingerprint TEXT,

    hash_algorithm TEXT,

    status_code INTEGER,

    content_type TEXT,

    headers BYTEA,

    body BYTEA,

    created_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,

    expires_at TIMESTAMPTZ NOT NULL
);

CREATE INDEX IF NOT EXISTS idx_idempotency_expires
    ON idempotency_keys (expires_at);

Important

state and lease_id are mandatory. The provider claims ownership of a key by writing state = 'in_progress' with a generated lease_id; only the holder of that lease may complete or release the entry. A table created without those columns fails on the first request.

The script is idempotent and safe to run on every deployment.

⚡ Why PostgreSQL?

PostgreSQL is ideal for:

• Financial systems
• Transactional applications
• Long-term persistence
• Existing PostgreSQL infrastructure
• Applications requiring durability

📊 Characteristics

📚 Documentation

Complete documentation includes:

• Installation
• Database schema
• Configuration
• Maintenance
• Performance considerations

🤝 Contributing

Contributions, bug reports and feature requests are always welcome. Fork the repository, create a feature branch, and open a pull request.

📄 License

Released under the MIT License.