PollySqlClient 1.0.1

PollySqlClient

Polly v8 resilience for SQL Server and Azure SQL — retry, timeout, and circuit-breaker for SqlConnection queries and commands, plus a built-in SqlServerTransientErrors predicate covering all common SQL Server and Azure SQL transient error numbers. Zero changes to your existing SQL.

// Before
await cmd.ExecuteNonQueryAsync();

// After — automatic retry + timeout on every operation
var resilient = connection.WithPolly(pipeline =>
    pipeline
        .AddRetry(new RetryStrategyOptions
        {
            MaxRetryAttempts = 3,
            ShouldHandle = SqlServerTransientErrors.IsTransient, // built-in ✔
        })
        .AddTimeout(TimeSpan.FromSeconds(30)));

await resilient.ExecuteAsync("INSERT INTO Orders (CustomerId) VALUES (@id)",
    parameters: [new SqlParameter("@id", customerId)]);

Installation

dotnet add package PollySqlClient

Targets net6.0, net8.0, and net9.0. Dependencies: Polly.Core 8.*, Microsoft.Data.SqlClient 6.*, Microsoft.Extensions.DependencyInjection.Abstractions 8.*

SqlServerTransientErrors — the key feature

Knowing which SQL Server errors are safe to retry is the hard part. PollySqlClient ships a pre-built SqlServerTransientErrors.IsTransient predicate so you don't have to look up error numbers.

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

SQL Server errors

Azure SQL errors

The raw set is also available for extension:

var myErrors = SqlServerTransientErrors.ErrorNumbers.ToHashSet();
myErrors.Add(4060); // Cannot open database (sometimes transient)

new RetryStrategyOptions
{
    ShouldHandle = new PredicateBuilder().Handle<SqlException>(ex =>
        ex.Errors.Cast<SqlError>().Any(e => myErrors.Contains(e.Number)))
}

Quick start

Inline pipeline

using PollySqlClient;

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

await resilient.OpenAsync();

// Non-query
await resilient.ExecuteAsync(
    "INSERT INTO Events (Type, Payload) VALUES (@type, @payload)",
    parameters: [new("@type", "OrderPlaced"), new("@payload", json)]);

// Query with mapper
var orders = await resilient.QueryAsync(
    "SELECT Id, Total FROM Orders WHERE CustomerId = @id",
    reader => new Order(reader.GetInt32(0), reader.GetDecimal(1)),
    parameters: [new SqlParameter("@id", customerId)]);

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

Dependency injection

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

builder.Services.AddPollySqlClient(pipeline =>
    pipeline
        .AddRetry(new RetryStrategyOptions
        {
            MaxRetryAttempts = 3,
            Delay = TimeSpan.FromMilliseconds(200),
            BackoffType = DelayBackoffType.Exponential,
            ShouldHandle = SqlServerTransientErrors.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(SqlConnection 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 CustomerId = @id",
            r => new Order(r.GetInt32(0), r.GetDecimal(1)),
            parameters: [new SqlParameter("@id", customerId)]);
    }
}

Supported operations

Pipeline order

[Timeout] → [Retry] → [Circuit Breaker] → [SqlClient]

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
PollyNpgsql		Polly v8 resilience for Npgsql (PostgreSQL) with PostgresTransientErrors predicate
PollyDapper		Polly v8 resilience for Dapper (works with any IDbConnection)
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
PollyAzureEventHub	Polly v8 for Azure Event Hubs
PollyAzureServiceBus		Polly v8 resilience for Azure Service Bus
PollyRedis		Polly v8 resilience for StackExchange.Redis
PollyMediatR		Polly v8 resilience for MediatR
PollyOpenAI		Polly v8 resilience for OpenAI and Azure OpenAI
PollyHealthChecks		ASP.NET Core health checks for Polly v8 circuit breakers
PollyElasticsearch	Polly v8 for Elastic.Clients.Elasticsearch
PollyAzureKeyVault	Polly v8 for Azure Key Vault
PollySendGrid	Polly v8 for SendGrid
PollyMassTransit	Polly v8 for MassTransit
PollyAzureTableStorage	Polly v8 for Azure Table Storage
PollyMailKit	MailKit SMTP email client
PollyAzureQueueStorage	Azure Queue Storage QueueClient
PollyHangfire	Hangfire IBackgroundJobClient
PollyBackoff		Jitter, linear & custom backoff for Polly v8 retry

💼 Need .NET consulting?

The author of this package is available for consulting on Polly v8 resilience, Azure cloud architecture, and clean .NET design.

→ solidqualitysolutions.com · LinkedIn

License

MIT