Postgres perf, path migration, and shutdown race fixes

- Major query performance boost: replaced correlated subqueries with DistinctBy() in BaseItemRepository, added episode deduplication index, and increased default command timeout to 120s. - Fixed LibraryMonitor shutdown race: added disposal checks and exception handling in FileRefresher to prevent ObjectDisposedException. - Added PowerShell and SQL utilities for fixing Linux paths in config files and database; new scripts for WebDir and path migration. - Auto-fix for WebDir in startup.json on load; new helper scripts and docs. - Added automated weekly DB performance monitoring scripts and reporting. - Expanded documentation and README for all fixes, scripts, and migration steps. - Updated SQL scripts for index creation and diagnostics; improved output handling. - Updated db-config defaults and added new diagnostic/report files.
2026-03-05 08:56:42 -05:00
parent 0eb44818ff
commit 7eb2b445cb
44 changed files with 3504 additions and 23 deletions
@@ -0,0 +1,108 @@
+# Windows Path Fix for Jellyfin PostgreSQL Database
+
+## Problem
+Logger shows Linux paths on Windows machine:
+```
+[WRN] Image not found at "/var/lib/jellyfin/metadata/People/D/David L.M. McIntyre/folder.jpg"
+```
+
+This happens because:
+1. **Paths are stored in the database** (not computed at runtime)
+2. You likely migrated from a Linux installation or imported data with Linux paths
+3. The database contains absolute Linux paths that don't exist on Windows
+
+## Root Cause
+The `ImageInfo.Path` and `BaseItemEntity.Path` fields store **absolute file paths** in the database.
+When you migrate from Linux to Windows, these paths aren't automatically converted.
+
+## Solutions
+
+### **Solution 1: Run SQL Script to Fix Paths** (Quick Fix)
+
+1. **Backup your database first!**
+   ```powershell
+   pg_dump -h localhost -U jellyfin -d jellyfin > jellyfin_backup_$(Get-Date -Format 'yyyyMMdd_HHmmss').sql
+   ```
+
+2. **Run the path fix script:**
+   ```powershell
+   psql -h localhost -U jellyfin -d jellyfin -f fix_windows_paths.sql
+   ```
+
+3. **Review the preview** - The script shows what will be changed without modifying data
+
+4. **Uncomment the UPDATE statements** in the script and run again to apply changes
+
+5. **Restart Jellyfin**
+
+### **Solution 2: Rebuild Metadata** (Clean Approach)
+
+If you have a small library, it may be easier to rebuild metadata:
+
+1. Dashboard → Library → Scan All Libraries
+2. Dashboard → Scheduled Tasks → "Scan Media Library" → Run
+3. This will recreate image paths with correct Windows paths
+
+### **Solution 3: Manual Database Query** (For specific items)
+
+If only a few items are affected, you can fix them manually:
+
+```sql
+-- Find People with Linux paths
+SELECT "Id", "Path" 
+FROM library."ImageInfos" 
+WHERE "Path" LIKE '/var/lib/jellyfin/metadata/People/%';
+
+-- Update a specific Person's image path
+UPDATE library."ImageInfos"
+SET "Path" = 'C:\ProgramData\jellyfin\data\metadata\People\D\David L.M. McIntyre\folder.jpg'
+WHERE "Id" = <your_id>;
+```
+
+## Prevention
+
+To avoid this issue in the future:
+
+1. **Use consistent paths** when migrating between OSes
+2. **Consider using virtual paths** (e.g., `%MetadataPath%\People\...` instead of absolute paths)
+3. **Test migrations** with a small dataset first
+
+## Notes
+
+- Windows accepts **both** forward slashes (`/`) and backslashes (`\`) in paths
+- However, the logger will show whatever is stored in the database
+- The script converts `/var/lib/jellyfin` → `C:/ProgramData/jellyfin/data`
+- Adjust the script if your Windows Jellyfin data directory is different
+
+## Checking Your Current Paths
+
+Run this to see what paths are in your database:
+
+```sql
+-- Show sample ImageInfo paths
+SELECT "Id", "Path" 
+FROM library."ImageInfos" 
+WHERE "Path" LIKE '/var/%' OR "Path" LIKE '/usr/%'
+LIMIT 10;
+
+-- Count Linux vs Windows paths
+SELECT 
+    COUNT(CASE WHEN "Path" LIKE '/var/%' OR "Path" LIKE '/usr/%' THEN 1 END) AS linux_paths,
+    COUNT(CASE WHEN "Path" LIKE 'C:%' OR "Path" LIKE 'D:%' THEN 1 END) AS windows_paths,
+    COUNT(*) AS total_paths
+FROM library."ImageInfos";
+```
+
+## Your Specific Case
+
+Based on the error:
+```
+/var/lib/jellyfin/metadata/People/D/David L.M. McIntyre/folder.jpg
+```
+
+Should be converted to:
+```
+C:\ProgramData\jellyfin\data\metadata\People\D\David L.M. McIntyre\folder.jpg
+```
+
+Or if your Jellyfin data directory is different, adjust accordingly.