Merge pull request #966 from Chris0Jeky/fix/perf-14-dbcontext-resilience

Add DbContext connection resilience (timeout and retry)

Author: Chris0Jeky

backend/src/Taskdeck.Api/appsettings.json

@@ -116,6 +116,9 @@
     "EncryptionKey": ""
   },
   "AllowedHosts": "*",
+  "Database": {
+    "CommandTimeoutSeconds": 30
+  },
   "ConnectionStrings": {
     "DefaultConnection": "Data Source=taskdeck.db"
   },

backend/src/Taskdeck.Application/Services/DatabaseSettings.cs

@@ -0,0 +1,20 @@
+using System.ComponentModel.DataAnnotations;
+
+namespace Taskdeck.Application.Services;
+
+/// <summary>
+/// Configuration for DbContext connection resilience.
+/// Bound from appsettings.json "Database" section.
+/// </summary>
+public sealed class DatabaseSettings
+{
+    /// <summary>
+    /// Command timeout in seconds for database operations.
+    /// Applied to <c>SqliteDbContextOptionsBuilder.CommandTimeout</c>.
+    /// This affects all EF Core commands including migrations
+    /// (<c>Database.Migrate()</c>). Avoid setting very low values (e.g. 1s)
+    /// if schema migrations are expected.
+    /// </summary>
+    [Range(1, 300, ErrorMessage = "CommandTimeoutSeconds must be between 1 and 300.")]
+    public int CommandTimeoutSeconds { get; set; } = 30;
+}

backend/src/Taskdeck.Infrastructure/DependencyInjection.cs

@@ -20,8 +20,24 @@ public static IServiceCollection AddInfrastructure(this IServiceCollection servi
         var connectionString = configuration.GetConnectionString("DefaultConnection")
             ?? "Data Source=taskdeck.db";
 
+        var databaseSettings = configuration.GetSection("Database").Get<DatabaseSettings>()
+            ?? new DatabaseSettings();
+
+        // Enforce validation for all host modes (API, CLI, MCP).
+        // ValidateOnStart causes an exception at startup if CommandTimeoutSeconds
+        // is out of the [1, 300] range, regardless of which host runs AddInfrastructure.
+        services.AddOptions<DatabaseSettings>()
+            .Bind(configuration.GetSection("Database"))
+            .ValidateDataAnnotations()
+            .ValidateOnStart();
+
         services.AddDbContext<TaskdeckDbContext>(options =>
-            options.UseSqlite(connectionString));
+            options.UseSqlite(connectionString, sqliteOptions =>
+            {
+                // Apply command timeout from configuration (default: 30s).
+                // This applies to all EF Core commands including Database.Migrate().
+                sqliteOptions.CommandTimeout(databaseSettings.CommandTimeoutSeconds);
+            }));
 
         services.AddScoped<IBoardRepository, BoardRepository>();
         services.AddScoped<IColumnRepository, ColumnRepository>();

backend/tests/Taskdeck.Api.Tests/Validation/OptionsValidationTests.cs

@@ -496,6 +496,54 @@ public void SecurityHeadersSettings_DefaultValues_PassValidation()
         Assert.True(isValid);
     }
 
+    // ── DatabaseSettings data annotation validation ───────────────────
+
+    [Fact]
+    public void DatabaseSettings_DefaultValues_PassValidation()
+    {
+        var settings = new DatabaseSettings();
+
+        var context = new System.ComponentModel.DataAnnotations.ValidationContext(settings);
+        var results = new List<System.ComponentModel.DataAnnotations.ValidationResult>();
+        var isValid = System.ComponentModel.DataAnnotations.Validator.TryValidateObject(
+            settings, context, results, validateAllProperties: true);
+
+        Assert.True(isValid);
+    }
+
+    [Theory]
+    [InlineData(0)]
+    [InlineData(-1)]
+    [InlineData(301)]
+    public void DatabaseSettings_CommandTimeoutSeconds_RejectsOutOfRange(int value)
+    {
+        var settings = new DatabaseSettings { CommandTimeoutSeconds = value };
+
+        var context = new System.ComponentModel.DataAnnotations.ValidationContext(settings);
+        var results = new List<System.ComponentModel.DataAnnotations.ValidationResult>();
+        var isValid = System.ComponentModel.DataAnnotations.Validator.TryValidateObject(
+            settings, context, results, validateAllProperties: true);
+
+        Assert.False(isValid);
+        Assert.Contains(results, r => r.MemberNames.Contains(nameof(DatabaseSettings.CommandTimeoutSeconds)));
+    }
+
+    [Theory]
+    [InlineData(1)]
+    [InlineData(30)]
+    [InlineData(300)]
+    public void DatabaseSettings_CommandTimeoutSeconds_AcceptsValidValues(int value)
+    {
+        var settings = new DatabaseSettings { CommandTimeoutSeconds = value };
+
+        var context = new System.ComponentModel.DataAnnotations.ValidationContext(settings);
+        var results = new List<System.ComponentModel.DataAnnotations.ValidationResult>();
+        var isValid = System.ComponentModel.DataAnnotations.Validator.TryValidateObject(
+            settings, context, results, validateAllProperties: true);
+
+        Assert.True(isValid);
+    }
+
     // ── AuditRetentionSettings ────────────────────────────────────────
 
     [Fact]

docs/platform/CONFIGURATION_REFERENCE.md

@@ -54,6 +54,7 @@ Source files used to build this reference:
   - [`AuditRetention`](#auditretention)
 - [Persistence and first run](#persistence-and-first-run)
   - [`ConnectionStrings`](#connectionstrings)
+  - [`Database`](#database)
   - [`ExportImport`](#exportimport)
   - [`FirstRun`](#firstrun)
   - [`DevelopmentSandbox`](#developmentsandbox)
@@ -492,6 +493,15 @@ DbContext) and
 | --- | --- | --- | --- | --- |
 | `ConnectionStrings:DefaultConnection` | `string` | `Data Source=taskdeck.db` | SQLite connection string. When `FirstRun:ResolveAppDataDbPath` is true and the path is relative, first-run resolves it into the OS LocalAppData directory (`%LOCALAPPDATA%/Taskdeck` on Windows, XDG equivalent on Linux). | Yes (but a default is always supplied) |
 
+### `Database`
+
+Consumed by `Taskdeck.Infrastructure.DependencyInjection.AddInfrastructure`.
+Backs `DatabaseSettings` (`Taskdeck.Application.Services.DatabaseSettings`).
+
+| Key | Type | Default | Description | Required? |
+| --- | --- | --- | --- | --- |
+| `Database:CommandTimeoutSeconds` | `int` | `30` | Command timeout in seconds for database operations. Valid range: 1--300. Applies to all EF Core commands including `Database.Migrate()` -- avoid very low values if schema migrations are expected. | No |
+
 ### `ExportImport`
 
 Consumed directly by `SettingsRegistration.cs`. Backs