PollyNpgsql 1.0.0

PollyNpgsql

Polly v8 resilience for Npgsql (PostgreSQL) — retry, timeout, and circuit-breaker for NpgsqlConnection queries and commands, plus a built-in PostgresTransientErrors predicate covering all common PostgreSQL transient SQLSTATE codes. Zero changes to your existing SQL.

// One line of setup
var resilient = connection.WithPolly(pipeline =>
    pipeline
        .AddRetry(new RetryStrategyOptions
        {
            MaxRetryAttempts = 3,
            ShouldHandle = PostgresTransientErrors.IsTransient, // built-in ✔
        })
        .AddTimeout(TimeSpan.FromSeconds(10)));

// Use exactly like NpgsqlConnection
var orders = await resilient.QueryAsync(
    "SELECT id, total FROM orders WHERE customer_id = $1",
    r => new Order(r.GetInt32(0), r.GetDecimal(1)),
    parameters: [new NpgsqlParameter { Value = customerId }]);

Installation

dotnet add package PollyNpgsql

Targets net6.0, net8.0, and net9.0. Dependencies: Polly.Core 8.*, Npgsql 9.*, Microsoft.Extensions.DependencyInjection.Abstractions 8.*

PostgresTransientErrors — the key feature

Knowing which PostgreSQL errors are safe to retry is the hard part. PollyNpgsql ships a pre-built PostgresTransientErrors.IsTransient predicate so you don't have to look up SQLSTATE codes.

new RetryStrategyOptions
{
    MaxRetryAttempts = 3,
    ShouldHandle = PostgresTransientErrors.IsTransient,
}

The raw set is also available if you need to extend it:

// Add custom codes
var myStates = PostgresTransientErrors.SqlStates.ToHashSet();
myStates.Add("57014"); // query_canceled (e.g. statement_timeout)

new RetryStrategyOptions
{
    ShouldHandle = new PredicateBuilder().Handle<NpgsqlException>(ex =>
        ex is PostgresException pg && myStates.Contains(pg.SqlState))
}

Quick start

Inline pipeline

using PollyNpgsql;

await using var connection = new NpgsqlConnection(connectionString);
var resilient = connection.WithPolly(pipeline =>
    pipeline
        .AddRetry(new RetryStrategyOptions
        {
            MaxRetryAttempts = 3,
            Delay = TimeSpan.FromMilliseconds(200),
            BackoffType = DelayBackoffType.Exponential,
            ShouldHandle = PostgresTransientErrors.IsTransient,
        })
        .AddTimeout(TimeSpan.FromSeconds(30)));

await resilient.OpenAsync();

// Execute non-query
await resilient.ExecuteAsync(
    "INSERT INTO events (type, payload) VALUES ($1, $2)",
    parameters: [new("type") { Value = "OrderPlaced" }, new("payload") { Value = json }]);

// Query with mapper
var orders = await resilient.QueryAsync(
    "SELECT id, total FROM orders WHERE customer_id = $1",
    reader => new Order(reader.GetInt32(0), reader.GetDecimal(1)),
    parameters: [new NpgsqlParameter { Value = customerId }]);

// Scalar
var count = await resilient.ExecuteScalarAsync<long>("SELECT COUNT(*) FROM orders");

Dependency injection

// Program.cs
builder.Services.AddScoped(_ => new NpgsqlConnection(connectionString));

builder.Services.AddPollyNpgsql(pipeline =>
    pipeline
        .AddRetry(new RetryStrategyOptions
        {
            MaxRetryAttempts = 3,
            Delay = TimeSpan.FromMilliseconds(200),
            BackoffType = DelayBackoffType.Exponential,
            ShouldHandle = PostgresTransientErrors.IsTransient,
        })
        .AddTimeout(TimeSpan.FromSeconds(30))
        .AddCircuitBreaker(new CircuitBreakerStrategyOptions
        {
            FailureRatio = 0.5,
            MinimumThroughput = 10,
            SamplingDuration = TimeSpan.FromSeconds(30),
            BreakDuration = TimeSpan.FromSeconds(15),
        }));

// Repository
public class OrderRepository(NpgsqlConnection db, ResiliencePipeline pipeline)
{
    public async Task<List<Order>> GetByCustomerAsync(int customerId)
    {
        var resilient = db.WithPolly(pipeline);
        await resilient.OpenAsync();
        return await resilient.QueryAsync(
            "SELECT id, total FROM orders WHERE customer_id = $1",
            r => new Order(r.GetInt32(0), r.GetDecimal(1)),
            parameters: [new NpgsqlParameter { Value = customerId }]);
    }
}

Supported operations

Pipeline order

[Timeout] → [Retry] → [Circuit Breaker] → [Npgsql]

pipeline
    .AddTimeout(TimeSpan.FromSeconds(30))   // 1. Overall deadline
    .AddRetry(retryOptions)                 // 2. Retry transient failures
    .AddCircuitBreaker(cbOptions)           // 3. Open circuit under load

Related packages

Package	Downloads	Description
PollyDapper		Polly v8 resilience for Dapper (works with any IDbConnection including Npgsql)
PollyEFCore		Polly v8 resilience for EF Core queries and SaveChanges
PollyMongo		Polly v8 resilience for MongoDB.Driver
PollyAzureBlob		Polly v8 resilience for Azure Blob Storage
PollyRedis		Polly v8 resilience for StackExchange.Redis
PollyMediatR		Polly v8 resilience pipelines for MediatR
PollyAzureServiceBus		Polly v8 resilience for Azure Service Bus
PollyHealthChecks		ASP.NET Core health checks for Polly v8 circuit breakers
PollyBackoff		Jitter, linear & custom backoff for Polly v8 retry

License

MIT