Add DecentDB migration guide and enhance health checks

- Introduced detailed DecentDB usage and migration documentation to guide users through resolving unsupported file-format errors.
- Updated Admin dashboard to display specific DecentDB health issues, linking to the migration guide for easier resolution.
- Improved `Doctor` service and dashboard logic to surface health check results for incompatible DecentDB files.
- Enhanced test coverage for health checks and migration scenarios.

Author: sphildreth

.github/workflows/dotnet.yml

@@ -74,7 +74,8 @@ jobs:
         Jwt__Audience: "test"
         security__secretKey: "testsecretkeytestsecretkeytestsecretkey"
         QuartzDisabled: "true"
-      run: dotnet test --no-build --verbosity normal --collect:"XPlat Code Coverage" --settings coverage.runsettings --results-directory coverage/results
+      # Parallel solution-level VSTest with coverage can return a non-zero exit after successful test summaries.
+      run: dotnet test --no-build -m:1 --verbosity normal --collect:"XPlat Code Coverage" --settings coverage.runsettings --results-directory coverage/results
     - name: Generate coverage report
       run: |
         dotnet tool install -g dotnet-reportgenerator-globaltool

docs/_data/toc.yml

@@ -20,6 +20,8 @@
       url: "hardware"
     - title: "Backup & Recovery"
       url: "backup"
+    - title: "DecentDB Usage & Migration"
+      url: "decentdb"
 
 - title: Core Concepts
   links:

docs/pages/changelog.md

@@ -23,6 +23,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Added public DecentDB usage and migration documentation covering Melodee's
+  generated search databases and rebuild steps for unsupported file-format
+  errors.
+
+### Fixed
+
+- Admin dashboard and login health warnings now open-check MusicBrainz and
+  ArtistSearch DecentDB files and link to the migration guide when unsupported
+  DecentDB file-format versions are detected.
+
 ## [2.1.3] - 2026-06-15
 
 ### Added

docs/pages/cli/doctor.md

@@ -29,8 +29,8 @@ mcli doctor [OPTIONS]
    - Validates required connection strings exist
 2. **Database connectivity**
    - Postgres (`DefaultConnection`)
-   - MusicBrainz SQLite (`MusicBrainzConnection`)
-   - ArtistSearchEngine SQLite (`ArtistSearchEngineConnection`)
+   - MusicBrainz DecentDB (`MusicBrainzConnection`)
+   - ArtistSearchEngine DecentDB (`ArtistSearchEngineConnection`)
 3. **Library paths**
    - Ensures each configured library path exists
    - Optionally validates write access with `--write-test`
@@ -60,8 +60,8 @@ mcli doctor [OPTIONS]
 ```
 ✓ Configuration
 ✓ Database: Postgres
-✓ Database: MusicBrainz (SQLite)
-✓ Database: ArtistSearchEngine (SQLite)
+✓ Database: MusicBrainz (DecentDB)
+✓ Database: ArtistSearchEngine (DecentDB)
 ✓ Libraries
 
 All checks passed.

docs/pages/decentdb.md

@@ -0,0 +1,218 @@
+---
+title: DecentDB Usage & Migration
+description: How Melodee uses DecentDB, how to diagnose compatibility issues, and how to rebuild generated DecentDB search databases.
+permalink: /decentdb/
+tags:
+  - decentdb
+  - migration
+  - troubleshooting
+---
+
+## Overview
+
+Melodee uses DecentDB for local, generated search databases. These files are
+separate from the primary Melodee PostgreSQL database and can be rebuilt from
+source data when necessary.
+
+DecentDB is currently used for:
+
+- **MusicBrainz search data**: the local MusicBrainz artist, alias, relation,
+  and album lookup database.
+- **Artist search cache**: the local artist search repository used to speed up
+  artist matching and enrichment.
+
+Melodee does not store user accounts, playlists, play history, ratings, or
+library metadata in these DecentDB files. Those records live in the primary
+PostgreSQL database.
+
+## Configuration
+
+The DecentDB databases are configured with these connection strings:
+
+| Connection string | Purpose |
+|-------------------|---------|
+| `MusicBrainzConnection` | Local MusicBrainz lookup database |
+| `ArtistSearchEngineConnection` | Local artist search cache database |
+
+In container deployments, the same values can be supplied with environment
+variables:
+
+```bash
+ConnectionStrings__MusicBrainzConnection="Data Source=/app/storage/_search-engines/musicbrainz/musicbrainz.ddb"
+ConnectionStrings__ArtistSearchEngineConnection="Data Source=/app/storage/_search-engines/artistSearchEngine.ddb"
+```
+
+Use your configured paths as the source of truth. Older installations may use
+`.db` filenames while newer examples use `.ddb`; the connection string path is
+what matters.
+
+## Doctor Compatibility Checks
+
+Doctor opens both DecentDB files with the current Melodee DecentDB provider. If
+the file was created by a newer or incompatible DecentDB engine, Doctor reports
+an issue similar to:
+
+```text
+MusicBrainz DecentDB database uses a file format that is not supported by the current DecentDB provider.
+Provider error: unsupported DecentDB file format version 11
+```
+
+This means the current Melodee process cannot safely read that generated search
+database. Search and enrichment may continue in degraded mode, but the affected
+database should be rebuilt or the Melodee/DecentDB package version should be
+updated.
+
+## Migration Strategy
+
+For Melodee's generated DecentDB files, migration usually means rebuilding the
+affected generated database with the current Melodee version. This is safer than
+trying to manually edit a DecentDB file created by an incompatible provider.
+
+Use this order:
+
+1. Upgrade Melodee to the intended version.
+2. Stop Melodee so no process is writing to the DecentDB files.
+3. Back up the affected `.ddb` file and any companion WAL or shared-memory
+   files.
+4. Move the incompatible generated database out of the active path.
+5. Start Melodee.
+6. Rebuild the affected database from Melodee.
+7. Run Doctor again and confirm the DecentDB checks pass.
+
+## Backup Before Rebuild
+
+Back up the main database and generated DecentDB files before changing anything.
+The example below preserves common DecentDB companion file names.
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+backup_root="$HOME/melodee-decentdb-backup-$(date +%Y%m%d-%H%M%S)"
+mkdir -p "$backup_root"
+
+musicbrainz_db="/path/to/search-engine-storage/musicbrainz/musicbrainz.ddb"
+artist_search_db="/path/to/search-engine-storage/artistSearchEngine.ddb"
+
+backup_decentdb_file() {
+  local db_path="$1"
+  local db_name
+  db_name="$(basename "$db_path")"
+
+  for suffix in "" ".wal" "-wal" ".shm" "-shm"; do
+    if [ -f "${db_path}${suffix}" ]; then
+      cp -a "${db_path}${suffix}" "$backup_root/${db_name}${suffix}"
+    fi
+  done
+}
+
+backup_decentdb_file "$musicbrainz_db"
+backup_decentdb_file "$artist_search_db"
+
+echo "Backed up DecentDB files to $backup_root"
+```
+
+Also back up PostgreSQL before a Melodee upgrade. See
+[Backup & Recovery](/backup/) for full backup guidance.
+
+## Example: Rebuild Incompatible DecentDB Files
+
+This example renames incompatible generated DecentDB files so Melodee can create
+fresh files with the current provider.
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+stamp="$(date +%Y%m%d-%H%M%S)"
+
+musicbrainz_db="/path/to/search-engine-storage/musicbrainz/musicbrainz.ddb"
+artist_search_db="/path/to/search-engine-storage/artistSearchEngine.ddb"
+
+move_decentdb_file_aside() {
+  local db_path="$1"
+
+  for suffix in "" ".wal" "-wal" ".shm" "-shm"; do
+    if [ -f "${db_path}${suffix}" ]; then
+      mv "${db_path}${suffix}" "${db_path}${suffix}.unsupported-$stamp"
+    fi
+  done
+}
+
+# Stop Melodee before moving active database files.
+# podman compose down
+# docker compose down
+
+move_decentdb_file_aside "$musicbrainz_db"
+move_decentdb_file_aside "$artist_search_db"
+
+# Start Melodee again.
+# podman compose up -d
+# docker compose up -d
+```
+
+After the files are moved aside, rebuild the generated databases.
+
+### MusicBrainz
+
+Use one of these options:
+
+- In the web UI, go to **Admin > Doctor** and use **Generate MusicBrainz
+  Database**.
+- In the web UI, go to **Admin > Jobs** and run
+  `MusicBrainzUpdateDatabaseJob`.
+- From the CLI, run:
+
+```bash
+./mcli job musicbrainz-update
+```
+
+MusicBrainz rebuilds can take a long time because Melodee downloads and imports
+the MusicBrainz dump into a local DecentDB file.
+
+### Artist Search Cache
+
+Use one of these options:
+
+- In the web UI, go to **Admin > Jobs** and run
+  `ArtistSearchEngineRepositoryHousekeepingJob`.
+- From the CLI, run:
+
+```bash
+./mcli job artistsearchengine-refresh
+```
+
+The artist search cache is generated from Melodee's library data and configured
+artist search providers. It can be rebuilt after the incompatible file is moved
+aside.
+
+## Verify The Migration
+
+Run Doctor after rebuilding:
+
+```bash
+./mcli doctor --verbose
+```
+
+Or open **Admin > Doctor** in the web UI.
+
+The following checks should pass:
+
+- `MusicBrainzDatabase`
+- `ArtistSearchEngineDatabase`
+
+If Doctor still reports an unsupported DecentDB file format after rebuilding,
+confirm that:
+
+- Melodee is running the version you expect.
+- The active connection strings point to the rebuilt files.
+- No old `.wal`, `-wal`, `.shm`, or `-shm` companion files remain beside the
+  rebuilt database.
+- The app container or service was restarted after the rebuild.
+
+## What Not To Delete
+
+Do not delete the primary PostgreSQL database when resolving DecentDB search
+cache compatibility issues. The unsupported DecentDB file-format warning applies
+to generated local search databases, not the primary Melodee database.
+

src/Melodee.Blazor/Components/Pages/Admin/Dashboard.razor

@@ -54,6 +54,35 @@
         </RadzenColumn>
     </RadzenRow>
 
+    @if (!_isCheckingHealth && _systemHealthIssues.Length > 0)
+    {
+        <RadzenAlert AlertStyle="AlertStyle.Danger" Variant="Variant.Outlined" Icon="error">
+            <RadzenStack Gap="0.5rem">
+                <RadzenText TextStyle="TextStyle.Subtitle2" Style="margin: 0;">@L("Dashboard.IssuesDetected")</RadzenText>
+                @foreach (var issue in _systemHealthIssues)
+                {
+                    <RadzenText TextStyle="TextStyle.Body2" Style="margin: 0; overflow-wrap: anywhere;">
+                        @FormatHealthIssue(issue)
+                    </RadzenText>
+                }
+                @if (DashboardHealthWarningEvaluator.HasUnsupportedDecentDbIssue(_systemHealthIssues))
+                {
+                    <a href="@DashboardHealthWarningEvaluator.DecentDbMigrationGuideUrl"
+                       target="_blank"
+                       rel="noopener noreferrer"
+                       style="font-weight: 600;">
+                        @L("Dashboard.DecentDbMigrationGuide")
+                    </a>
+                }
+                <RadzenButton Text="@L("Navigation.Doctor")"
+                              Icon="health_and_safety"
+                              Click="@(() => NavigationManager.NavigateTo("/admin/doctor"))"
+                              Size="ButtonSize.Small"
+                              ButtonStyle="ButtonStyle.Danger"/>
+            </RadzenStack>
+        </RadzenAlert>
+    }
+
     <RadzenRow Gap="1rem">
         @* Quick Links *@
         <RadzenColumn Size="12" SizeMD="6">
@@ -502,6 +531,7 @@
     private string _melodeeVersion = "---";
     private string _apiVersion = "---";
     private string _osDescription = "---";
+    private Melodee.Common.Services.Doctor.DoctorCheckResult[] _systemHealthIssues = [];
     private bool _systemHealthy = true;
     private bool _isCheckingHealth = true;
 
@@ -648,10 +678,19 @@
         try
         {
             var results = await DoctorService.RunAllChecksAsync();
-            _systemHealthy = results.Checks.All(c => c.Success);
+            _systemHealthIssues = results.Checks.Where(c => !c.Success).Take(5).ToArray();
+            _systemHealthy = _systemHealthIssues.Length == 0;
         }
         catch
         {
+            _systemHealthIssues =
+            [
+                new Melodee.Common.Services.Doctor.DoctorCheckResult(
+                    "Doctor",
+                    false,
+                    "Doctor checks failed before returning results",
+                    TimeSpan.Zero)
+            ];
             _systemHealthy = false;
         }
         finally
@@ -661,6 +700,43 @@
         }
     }
 
+    private string FormatHealthIssue(Melodee.Common.Services.Doctor.DoctorCheckResult issue)
+    {
+        var name = LocalizeHealthIssueName(issue.Name);
+        return string.IsNullOrWhiteSpace(issue.Details)
+            ? name
+            : $"{name}: {issue.Details}";
+    }
+
+    private string LocalizeHealthIssueName(string checkName)
+    {
+        return checkName switch
+        {
+            "Configuration" => L("AdminDoctor.Check.Configuration"),
+            "PostgresDatabase" => L("AdminDoctor.Check.PostgresDatabase"),
+            "MusicBrainzDatabase" => L("AdminDoctor.Check.MusicBrainzDatabase"),
+            "ArtistSearchEngineDatabase" => L("AdminDoctor.Check.ArtistSearchEngineDatabase"),
+            "LibraryPaths" => L("AdminDoctor.Check.LibraryPaths"),
+            "SerilogLogging" => L("AdminDoctor.Check.SerilogLogging"),
+            "ConfigurableServices" => L("AdminDoctor.Check.ConfigurableServices"),
+            "DiskSpace" => L("AdminDoctor.Check.DiskSpace"),
+            "LibraryPathOverlap" => L("AdminDoctor.Check.LibraryPathOverlap"),
+            "SearchEngineApiKeys" => L("AdminDoctor.Check.SearchEngineApiKeys"),
+            "SmtpConfiguration" => L("AdminDoctor.Check.SmtpConfiguration"),
+            "JwtTokenStrength" => L("AdminDoctor.Check.JwtTokenStrength"),
+            "HttpsSecurity" => L("AdminDoctor.Check.HttpsSecurity"),
+            "AdminPassword" => L("AdminDoctor.Check.AdminPassword"),
+            "Scheduler" => L("AdminDoctor.Check.Scheduler"),
+            "FFmpeg" => L("AdminDoctor.Check.FFmpeg"),
+            "Memory" => L("AdminDoctor.Check.Memory"),
+            "TempDirectory" => L("AdminDoctor.Check.TempDirectory"),
+            "DatabaseLatency" => L("AdminDoctor.Check.DatabaseLatency"),
+            "JukeboxConfiguration" => L("AdminDoctor.Check.JukeboxConfiguration"),
+            "PodcastConfiguration" => L("AdminDoctor.Check.PodcastConfiguration"),
+            _ => checkName
+        };
+    }
+
     private void ClearCacheClicked()
     {
         CacheManager.Clear();