Veggerby.Ignition.SqlServer 0.5.0

Veggerby.Ignition.SqlServer

SQL Server readiness signals for Veggerby.Ignition - verify database connections and schema during application startup.

Installation

dotnet add package Veggerby.Ignition.SqlServer
dotnet add package Microsoft.Data.SqlClient

Usage

Modern Pattern: Connection Factory (Recommended)

The recommended approach uses a connection factory registered in DI for better connection management:

// Register connection factory in DI container
builder.Services.AddSingleton<Func<SqlConnection>>(() => 
    new SqlConnection("Server=localhost;Database=MyDb;Trusted_Connection=True;"));

// Add SQL Server readiness signal (automatically resolves factory from DI)
builder.Services.AddIgnition();
builder.Services.AddSqlServerReadiness();

var app = builder.Build();
await app.Services.GetRequiredService<IIgnitionCoordinator>().WaitAllAsync();

Why Connection Factory?

• Cleaner DI integration: No connection string duplication across services
• Centralized configuration: Single factory registration shared by all consumers
• Testability: Easy to mock or replace for testing
• Connection pooling: SQL Server connection pooling managed by ADO.NET

Legacy Pattern: Connection String

For simpler scenarios or when a connection factory isn't registered in DI:

builder.Services.AddIgnition();

builder.Services.AddSqlServerReadiness(
    "Server=localhost;Database=MyDb;Trusted_Connection=True;");

var app = builder.Build();
await app.Services.GetRequiredService<IIgnitionCoordinator>().WaitAllAsync();

With Validation Query

builder.Services.AddSingleton<Func<SqlConnection>>(() => new SqlConnection(connectionString));

builder.Services.AddSqlServerReadiness(options =>
{
    options.ValidationQuery = "SELECT 1";
    options.Timeout = TimeSpan.FromSeconds(5);
});

Advanced Schema Validation

builder.Services.AddSingleton<Func<SqlConnection>>(() => new SqlConnection(connectionString));

builder.Services.AddSqlServerReadiness(options =>
{
    // Verify specific table exists
    options.ValidationQuery = "SELECT TOP 1 1 FROM Users";
    options.Timeout = TimeSpan.FromSeconds(10);
});

Features

• Connection Verification: Validates database connectivity
• Optional Query Validation: Execute custom queries to verify schema readiness
• Activity Tracing: Tags for server, database, and validation queries
• Structured Logging: Information, Debug, and Error level diagnostics
• Idempotent Execution: Cached results prevent redundant connection attempts
• Thread-Safe: Concurrent readiness checks execute once

Configuration Options

Logging

The signal emits structured logs at different levels:

• Information: Connection attempts and successful completions
• Debug: Connection established, validation query execution
• Error: Connection failures, query execution failures

Activity Tracing

When tracing is enabled, the signal adds these tags:

• sqlserver.server: Data source from connection string
• sqlserver.database: Initial catalog from connection string
• sqlserver.validation_query: Validation query if configured

Examples

Health Check Integration

builder.Services.AddIgnition();
builder.Services.AddSqlServerReadiness(connectionString);

builder.Services
    .AddHealthChecks()
    .AddCheck<IgnitionHealthCheck>("ignition-readiness");

Multiple Databases

// Primary database
builder.Services.AddSqlServerReadiness(
    primaryConnectionString,
    options =>
    {
        options.ValidationQuery = "SELECT 1";
        options.Timeout = TimeSpan.FromSeconds(5);
    });

// Reporting database
builder.Services.AddSqlServerReadiness(
    reportingConnectionString,
    options =>
    {
        options.ValidationQuery = "SELECT 1";
        options.Timeout = TimeSpan.FromSeconds(10);
    });

Note: Currently, multiple SQL Server signals will share the same name ("sqlserver-readiness"). For distinct signals, implement custom IIgnitionSignal with unique names.

Error Handling

Connection failures and query execution errors are logged and propagated:

try
{
    await coordinator.WaitAllAsync();
}
catch (AggregateException ex)
{
    foreach (var inner in ex.InnerExceptions)
    {
        if (inner is SqlException sqlEx)
        {
            // Handle SQL Server-specific errors
            Console.WriteLine($"SQL Error {sqlEx.Number}: {sqlEx.Message}");
        }
    }
}

Performance

• Minimal allocations per signal invocation
• Connection pooling handled by Microsoft.Data.SqlClient
• Async throughout (no blocking I/O)
• Idempotent execution (connection attempted once)

License

MIT License. See LICENSE.