Skip to ContentSkip to Content
Configuration

Configuration

Every provider registration method in Forge.Repository accepts two configuration objects: ForgeDbContextPoolingOptions for connection pool settings, and a ForgeDbTuner delegate for provider-specific options like retry policies, timeouts, and spatial extensions.

AddForgeRepository* Signature

All provider extension methods share the same signature shape:

public static IServiceCollection AddForgeRepository{Provider}<TContext>(
    this IServiceCollection services,
    string connectionString,
    ForgeDbContextPoolingOptions poolingOptions,
    Action<ForgeDbTuner> configure)
    where TContext : Forge.Repository.DbContext
ParameterTypeDescription
connectionStringstringRaw connection string from your config
poolingOptionsForgeDbContextPoolingOptionsPooling behaviour - see below
configureAction<ForgeDbTuner>Retry, timeout, spatial options - see below

ForgeDbContextPoolingOptions

Controls how connections are pooled at both the ADO.NET level (via the driver’s connection string builder) and the EF Core level (pooled vs non-pooled DbContext).

public class ForgeDbContextPoolingOptions
{
    public bool EnablePooling { get; set; } = false;
    public int  MinPoolSize   { get; set; } = 1;
    public int  MaxPoolSize   { get; set; } = 10;
}

Properties

PropertyTypeDefaultDescription
EnablePoolingboolfalseWhen true, registers the DbContext with AddDbContextPool and sets Pooling=true in the connection string. When false, uses AddDbContext.
MinPoolSizeint1Minimum connections kept alive in the pool. Injected directly into the driver’s connection string.
MaxPoolSizeint10Maximum simultaneous connections. Injected directly into the driver’s connection string.

Pooling vs non-pooling

// Non-pooled (default) - suitable for development, low-traffic services
poolingOptions: new ForgeDbContextPoolingOptions
{
    EnablePooling = false
}
 
// Pooled - recommended for production web APIs
poolingOptions: new ForgeDbContextPoolingOptions
{
    EnablePooling = true,
    MinPoolSize   = 2,
    MaxPoolSize   = 100
}

When EnablePooling = true, Forge uses AddDbContextPool<TContext> which resets and reuses DbContext instances rather than creating new ones per request. This significantly reduces allocation pressure in high-throughput APIs. Note that DbContext pooling has restrictions  — your context must not have instance-level state that varies per request (outside of injected dependencies).

ForgeDbTuner

ForgeDbTuner wraps the provider-specific EF Core options builder and exposes three methods that map to IDbProviderTuner:

public interface IDbProviderTuner
{
    void ApplyRetry(int count);
    void ApplyTimeout(int seconds);
    void ApplySpatial();
}

You receive a ForgeDbTuner instance inside the configure delegate and call whichever methods apply to your scenario:

configure: tuner =>
{
    tuner.SetRetry(3);       // retry transient failures
    tuner.SetTimeout(60);    // command timeout in seconds
    tuner.SetSpatial();      // enable spatial types
}

SetRetry(int count)

Configures EF Core’s built-in execution strategy to retry on transient failures - connection resets, timeout exceptions, and database-specific transient error codes. The retry count is the maximum number of attempts (including the first).

tuner.SetRetry(3);   // first attempt + up to 2 retries
tuner.SetRetry(5);   // first attempt + up to 4 retries
ProviderUnderlying strategy
SQL ServerEnableRetryOnFailure(count)
PostgreSQLEnableRetryOnFailure(count)
OracleEnableRetryOnFailure(count)
MySQLEnableRetryOnFailure(count)

Retries use exponential back-off with jitter via EF Core’s default execution strategy. You do not need to configure this manually.

SetTimeout(int seconds)

Sets the command timeout - the maximum time in seconds that any single database command is allowed to run before EF Core throws a TimeoutException.

tuner.SetTimeout(30);    // 30 second command timeout
tuner.SetTimeout(120);   // 2 minute timeout for long reports

The default EF Core command timeout varies by provider (typically 30 seconds). Set a higher value for long-running batch jobs or reports.

ApplySpatial()

Enables spatial type support (geometry and geography types).

configure: tuner =>
{
    tuner.SetRetry(3);
    tuner.SetTimeout(30);
    tuner.ApplySpatial();
}

Full Configuration Examples

// Program.cs
builder.Services.AddForgeRepositorySqlServer<AppDbContext>(
    connectionString: builder.Configuration.GetConnectionString("SqlServer")!,
    poolingOptions: new ForgeDbContextPoolingOptions
    {
        EnablePooling = true,
        MinPoolSize   = 2,
        MaxPoolSize   = 50,
    },
    configure: tuner =>
    {
        tuner.SetRetry(3);
        tuner.SetTimeout(30);
        tuner.ApplySpatial();
    });

Reading Connection Strings

Connection strings should always come from appsettings.json or environment variables — never hardcode them.

// appsettings.json
{
  "ConnectionStrings": {
    "Default": "Server=localhost;Database=MyApp;Trusted_Connection=True;"
  }
}
// appsettings.Production.json (override for prod)
{
  "ConnectionStrings": {
    "Default": "Server=prod-sql.internal;Database=MyApp;User Id=app;Password=..."
  }
}
// Program.cs — prefer GetConnectionString over Configuration["..."]
builder.Services.AddForgeRepositorySqlServer<AppDbContext>(
    connectionString: builder.Configuration.GetConnectionString("Default")!,
    ...);

Custom Migration History Table (PostgreSQL)

The PostgreSQL provider automatically replaces EF Core’s default migration history repository with CustomHistoryRepository. This adjusts the schema name of __EFMigrationsHistory to avoid conflicts in PostgreSQL’s case-sensitive identifier rules.

No configuration is required - this is applied automatically when you use AddForgeRepositoryPostgreSql.

Quick StartEntities & Models