From 895372fe985653efd3493ef713718024abecc23e Mon Sep 17 00:00:00 2001 From: Wendell Jones Date: Tue, 3 Mar 2026 17:10:46 -0500 Subject: [PATCH] Move scripts to scripts directory and remove odcs no longer needed. --- build_warnings.txt | Bin 1608 -> 0 bytes database_report.txt | 142 -------- docs/PR-DESCRIPTION-SESSION-FIXES.md | 300 ----------------- docs/PR-DESCRIPTION-SHORT.md | 115 ------- docs/PR-QUICK-COPY.md | 84 ----- docs/PR_DESCRIPTION.md | 316 ------------------ docs/PR_DESCRIPTION_SHORT.md | 94 ------ editorconfig_new.txt | 28 -- .../Add-All-Indexes.bat | 0 .../Add-Base-Indexes.bat | 0 .../Add-Indexes-Quick.bat | 0 .../Add-Indexes-Quick.ps1 | 0 .../Fix-ItemValues-Performance.ps1 | 0 .../build-installer.ps1 | 0 .../copy-sql-files.ps1 | 0 db-config.ps1 => scripts/db-config.ps1 | 0 db-quick.ps1 => scripts/db-quick.ps1 | 0 .../publish-with-sql.ps1 | 0 .../rebuild-solution.ps1 | 0 .../remove-sqlite.ps1 | 0 20 files changed, 1079 deletions(-) delete mode 100644 build_warnings.txt delete mode 100644 database_report.txt delete mode 100644 docs/PR-DESCRIPTION-SESSION-FIXES.md delete mode 100644 docs/PR-DESCRIPTION-SHORT.md delete mode 100644 docs/PR-QUICK-COPY.md delete mode 100644 docs/PR_DESCRIPTION.md delete mode 100644 docs/PR_DESCRIPTION_SHORT.md delete mode 100644 editorconfig_new.txt rename Add-All-Indexes.bat => scripts/Add-All-Indexes.bat (100%) rename Add-Base-Indexes.bat => scripts/Add-Base-Indexes.bat (100%) rename Add-Indexes-Quick.bat => scripts/Add-Indexes-Quick.bat (100%) rename Add-Indexes-Quick.ps1 => scripts/Add-Indexes-Quick.ps1 (100%) rename Fix-ItemValues-Performance.ps1 => scripts/Fix-ItemValues-Performance.ps1 (100%) rename build-installer.ps1 => scripts/build-installer.ps1 (100%) rename copy-sql-files.ps1 => scripts/copy-sql-files.ps1 (100%) rename db-config.ps1 => scripts/db-config.ps1 (100%) rename db-quick.ps1 => scripts/db-quick.ps1 (100%) rename publish-with-sql.ps1 => scripts/publish-with-sql.ps1 (100%) rename rebuild-solution.ps1 => scripts/rebuild-solution.ps1 (100%) rename remove-sqlite.ps1 => scripts/remove-sqlite.ps1 (100%) diff --git a/build_warnings.txt b/build_warnings.txt deleted file mode 100644 index cfd0be54ee5b1656f8c14823e1c214b9f94fce69..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 1608 zcmcJPO;3YB5QgV$;(y?%2M9KvdN64%2ThuIF!92L7D{R=MZlBS-TQT#4165VcvFqZ~We)rJg_0RE(b7Vi9vXVi%dDM4~8Nx#1hgP(pcV za0rQ>qVd)58n``Jf849`v1@wieoA{g+{zuO{0mykb~IGPd{rZZDyrKBm82LVHr5zR)E? zH-=q2)%oemAJbKqyyzGfCF?mOG0w`{+ja--z&`VdOcdO-cFI&Pu({mP3DD5~Uex3o c>k%vM8`?ov_{lAo8rf$Ix8G~x4%n&941 second) ------------------------------------------ - pid | usename | application_name | duration | state | wait_event_type | wait_event | query_preview ------+---------+------------------+----------+-------+-----------------+------------+--------------- -(0 rows) - -Time: 10.143 ms - -3. TABLE SIZES (Top 10) ------------------------------------------ -Time: 17.735 ms - -4. INDEX USAGE (Tables with low index usage) ------------------------------------------ - schemaname | tablename | seq_scan | idx_scan | rows | index_usage_percent -------------+-----------------------+----------+----------+--------+--------------------- - library | ItemValues | 239123 | 262958 | 8802 | 52.37 - library | Peoples | 20780 | 331963 | 84061 | 94.11 - library | AttachmentStreamInfos | 533 | 19267 | 5085 | 97.31 - library | Chapters | 369 | 19220 | 18865 | 98.12 - library | BaseItems | 10683 | 2776087 | 112093 | 99.62 - library | MediaStreamInfos | 126 | 39129 | 60298 | 99.68 - library | BaseItemProviders | 2680 | 900431 | 155030 | 99.70 - library | ItemValuesMap | 431 | 237893 | 263683 | 99.82 - library | PeopleBaseItemMap | 15 | 127908 | 246523 | 99.99 - library | BaseItemImageInfos | 87 | 1025614 | 65607 | 99.99 -(10 rows) - -Time: 8.349 ms - -5. TABLES WITH HIGH SEQUENTIAL SCANS ------------------------------------------ - schemaname | tablename | seq_scan | seq_tup_read | idx_scan | n_live_tup | avg_rows_per_seq_scan -------------+-----------------------+----------+--------------+----------+------------+----------------------- - library | ItemValues | 239123 | 1426740382 | 262958 | 8802 | 5966 - library | Peoples | 20780 | 1038286642 | 331963 | 84061 | 49965 - library | BaseItems | 10683 | 379674076 | 2776087 | 112093 | 35540 - library | BaseItemProviders | 2680 | 1370592 | 900431 | 155030 | 511 - library | UserData | 15853658 | 458427 | 1 | 3 | 0 - library | ItemValuesMap | 431 | 96582 | 237893 | 263683 | 224 - library | AttachmentStreamInfos | 533 | 77460 | 19267 | 5085 | 145 - library | Chapters | 369 | 71596 | 19220 | 18865 | 194 - library | MediaStreamInfos | 126 | 11295 | 39129 | 60298 | 89 -(9 rows) - -Time: 9.443 ms - -6. TABLE BLOAT (Dead Tuples) ------------------------------------------ - schemaname | tablename | dead_tuples | live_tuples | dead_tuple_percent | last_vacuum | last_autovacuum | last_analyze | last_autoanalyze -------------+--------------------+-------------+-------------+--------------------+-------------+-------------------------------+-------------------------------+------------------------------- - library | BaseItems | 9743 | 112093 | 8.69 | | 2026-02-28 15:26:15.491132-05 | 2026-02-28 15:53:05.714737-05 | 2026-02-28 15:46:14.039634-05 - library | BaseItemImageInfos | 4933 | 65607 | 7.52 | | 2026-02-28 15:51:10.816013-05 | 2026-02-28 15:53:06.902228-05 | 2026-02-28 15:52:11.608171-05 - library | BaseItemProviders | 2468 | 155030 | 1.59 | | 2026-02-28 15:46:15.528943-05 | 2026-02-28 15:53:07.082623-05 | 2026-02-28 15:50:10.879895-05 -(3 rows) - -Time: 3.804 ms - -7. CACHE HIT RATIO (Should be >95%) ------------------------------------------ - metric | hit_ratio_percent -------------------------+------------------- - Buffer Cache Hit Ratio | -(1 row) - -Time: 3.750 ms - -8. UNUSED OR RARELY USED INDEXES ------------------------------------------ - schemaname | tablename | indexname | index_size | times_used | idx_tup_read | idx_tup_fetch -------------+-------------------+-----------------------------------------------------------------+------------+------------+--------------+--------------- - library | PeopleBaseItemMap | PK_PeopleBaseItemMap | 23 MB | 0 | 0 | 0 - library | ItemValuesMap | idx_itemvaluesmap_itemvalueid_itemid | 17 MB | 10 | 108 | 10 - library | ItemValuesMap | PK_ItemValuesMap | 17 MB | 0 | 0 | 0 - library | BaseItems | IX_BaseItems_Type_TopParentId_IsVirtualItem_PresentationUnique~ | 16 MB | 6 | 57709 | 4974 - library | BaseItems | IX_BaseItems_Path | 15 MB | 0 | 0 | 0 - library | BaseItems | IX_BaseItems_Type_TopParentId_Id | 13 MB | 0 | 0 | 0 - library | PeopleBaseItemMap | IX_PeopleBaseItemMap_ItemId_ListOrder | 13 MB | 0 | 0 | 0 - library | BaseItems | idx_baseitems_datecreated_filtered | 11 MB | 0 | 0 | 0 - library | BaseItemProviders | IX_BaseItemProviders_ProviderId_ProviderValue_ItemId | 10 MB | 0 | 0 | 0 - library | BaseItemProviders | baseitemproviders_providerid_idx | 8216 kB | 0 | 0 | 0 -(10 rows) - -Time: 16.869 ms - -9. CURRENT LOCKS (Blocked queries) ------------------------------------------ - blocked_pid | blocked_user | blocking_query | blocking_duration | blocked_query --------------+--------------+----------------+-------------------+--------------- -(0 rows) - -Time: 10.333 ms - -10. SLOWEST QUERIES (Requires pg_stat_statements extension) ------------------------------------------ -DO -Time: 10.465 ms -DO -Time: 144.695 ms - -11. KEY POSTGRESQL SETTINGS ------------------------------------------ - name | setting | unit | short_desc -------------------------------+---------+------+------------------------------------------------------------------------------------------ - autovacuum | on | | Starts the autovacuum subprocess. - checkpoint_completion_target | 0.9 | | Time spent flushing dirty buffers during checkpoint, as fraction of checkpoint interval. - default_statistics_target | 100 | | Sets the default statistics target. - effective_cache_size | 524288 | 8kB | Sets the planner's assumption about the total size of the data caches. - effective_io_concurrency | 16 | | Number of simultaneous requests that can be handled efficiently by the disk subsystem. - maintenance_work_mem | 131072 | kB | Sets the maximum memory to be used for maintenance operations. - max_connections | 100 | | Sets the maximum number of concurrent connections. - random_page_cost | 4 | | Sets the planner's estimate of the cost of a nonsequentially fetched disk page. - shared_buffers | 262144 | 8kB | Sets the number of shared memory buffers used by the server. - wal_buffers | 2048 | 8kB | Sets the number of disk-page buffers in shared memory for WAL. - work_mem | 1048576 | kB | Sets the maximum memory to be used for query workspaces. -(11 rows) - -Time: 6.588 ms - -12. RECOMMENDATIONS ------------------------------------------ -Time: 8.404 ms - -========================================= -Run sql/performance_indexes.sql to add missing indexes -See PERFORMANCE_TROUBLESHOOTING.md for detailed fixes -========================================= diff --git a/docs/PR-DESCRIPTION-SESSION-FIXES.md b/docs/PR-DESCRIPTION-SESSION-FIXES.md deleted file mode 100644 index 37261357..00000000 --- a/docs/PR-DESCRIPTION-SESSION-FIXES.md +++ /dev/null @@ -1,300 +0,0 @@ -# PostgreSQL Error Fixes and Enhancements - Production Ready - -## Overview - -This PR resolves **8 critical issues** and adds **3 major enhancements** to the Jellyfin PostgreSQL implementation, making it production-ready for high-concurrency environments. - -## Issues Fixed - -### 1. SQLite Migration Filtering ✅ -- **Problem:** PostgreSQL installations tried to backup non-existent SQLite files -- **Solution:** Added filtering to skip SQLite-specific migrations -- **Impact:** Clean startup without false errors - -### 2. Database Query Timeout ✅ -- **Problem:** Queries timing out after 30 seconds -- **Solution:** Configurable command timeout (default 120s) + performance indexes -- **Impact:** Queries complete in 2-10 seconds (3-15x faster) - -### 3. SyncPlay Authentication Errors ✅ -- **Problem:** Empty GUID causing ArgumentException with stack traces -- **Solution:** Validate user ID before calling `GetUserById()` -- **Impact:** Clean warning messages instead of scary errors - -### 4. Authentication Token Errors ✅ -- **Problem:** Missing tokens logged as errors with stack traces -- **Solution:** Detect authentication errors and log as warnings -- **Impact:** 80% reduction in log noise - -### 5. Database Deadlock Handling ✅ -- **Problem:** Deadlocks logged as errors, unclear if automatic retry worked -- **Solution:** Specific deadlock detection with informative warning message -- **Impact:** Clear indication that EF Core retry logic is handling it - -### 6. Constraint Violation - BaseItemProviders ✅ (Critical Fix) -- **Problem:** Duplicate key constraint violations during concurrent metadata refreshes -- **Solution:** - - Iteration 1: Improved error messages - - Iteration 2: EF Core UPSERT (partial fix) - - Iteration 3: Raw SQL with `ON CONFLICT` (race condition remained) - - **Iteration 4 (FINAL):** Raw SQL + Navigation property clearing -- **Root Cause:** EF Core was tracking navigation properties and re-inserting after raw SQL -- **Impact:** 100% success rate for concurrent metadata operations - -### 7. StyleCop Warnings ✅ -- **Problem:** SA1137 indentation warnings on pre-existing code -- **Solution:** Added suppression to `.editorconfig` -- **Impact:** Clean build output - -### 8. Remote PostgreSQL Backup Support ✅ -- **Problem:** Backups artificially disabled for remote PostgreSQL servers -- **Solution:** Removed localhost-only restriction -- **Impact:** Backups now work with remote databases - -## Enhancements - -### 1. Configurable Backup Disable Option -Added `disable-backups` configuration option for users who don't need built-in backups: - -```xml - - disable-backups - True - -``` - -### 2. LibraryMonitorDelay Now Configurable -Made file system monitoring delay configurable with validation: - -```xml -60 -``` - -- **Default:** 60 seconds -- **Minimum:** 30 seconds (enforced) -- **Purpose:** Adjust for different storage types (local SSD vs. network NAS) - -### 3. Comprehensive Documentation -Created 14 new documentation files covering: -- Complete configuration reference -- Remote backup setup -- Performance optimization -- Error troubleshooting -- File monitoring configuration - -## Files Changed - -### Core Code (8 files) -1. `Jellyfin.Server/Migrations/JellyfinMigrationService.cs` - SQLite migration filtering -2. `Jellyfin.Api/Auth/SyncPlayAccessPolicy/SyncPlayAccessHandler.cs` - SyncPlay validation -3. `Jellyfin.Api/Middleware/ExceptionMiddleware.cs` - Authentication error handling -4. `Jellyfin.Server.Implementations/Item/BaseItemRepository.cs` - **Critical UPSERT fix** -5. `src/Jellyfin.Database/Jellyfin.Database.Implementations/JellyfinDbContext.cs` - Generic constraint messages -6. `src/Jellyfin.Database/Jellyfin.Database.Providers.Postgres/PostgresDatabaseProvider.cs` - Remote backup + disable option -7. `MediaBrowser.Model/Configuration/ServerConfiguration.cs` - **NEW: LibraryMonitorDelay validation** -8. `.editorconfig` - StyleCop suppressions - -### Documentation (21 files) -- 14 new documentation files -- 7 existing files updated -- Complete configuration reference -- Performance optimization guides -- Troubleshooting documentation - -See [COMPLETE-SESSION-SUMMARY.md](docs/COMPLETE-SESSION-SUMMARY.md) for full details. - -## Breaking Changes - -**None** - All changes are backward compatible. - -## Migration Guide - -### Required Configuration Changes - -1. **Add command timeout** to `database.xml`: -```xml - - command-timeout - 120 - -``` - -2. **Run performance indexes** (highly recommended): -```bash -psql -U postgres -d jellyfin_db -f sql/add-performance-indexes.sql -``` - -3. **PostgreSQL client tools** (if using backups): -```bash -# Linux -sudo apt-get install postgresql-client - -# Verify -pg_dump --version -``` - -### Optional Configuration - -**Disable backups** (if using external backup solutions): -```xml - - disable-backups - True - -``` - -**Adjust file monitoring delay** (if needed): -```xml -60 -``` - -## Testing - -### Build Status -✅ All projects compile successfully -✅ No breaking changes -✅ All error scenarios tested - -### Verification Checklist -- [x] Library scans complete without errors -- [x] No SQLite migration errors on startup -- [x] Query timeouts resolved -- [x] Authentication errors log as warnings -- [x] Deadlocks handled gracefully -- [x] Metadata refresh works without constraint violations -- [x] Remote backups functional -- [x] LibraryMonitorDelay validation working - -## Performance Impact - -| Operation | Before | After | Improvement | -|-----------|--------|-------|-------------| -| Query Timeout | 30s (fails) | 2-10s | 3-15x faster | -| Library Scan | Frequent failures | 100% success | Fixed | -| Deadlock Recovery | Manual | Automatic | 95-99% success | -| Metadata Refresh | Constraint errors | No errors | 100% success | -| Log Noise | Many false alarms | Clear warnings | ~80% reduction | - -## Key Technical Details - -### Constraint Violation Fix (Most Complex) - -The fix went through 4 iterations: - -1. **Improved error messages** - Better logging -2. **EF Core UPSERT** - Still had tracking conflicts -3. **Raw SQL with ON CONFLICT** - Still had race conditions -4. **Raw SQL + Navigation property clearing** ✅ - **FINAL WORKING SOLUTION** - -**Critical insight:** After using `ExecuteSqlAsync`, must clear `entity.Provider = null` to prevent EF Core from re-tracking and re-inserting the providers. - -```csharp -// UPSERT with raw SQL -await context.Database.ExecuteSqlAsync( - $@"INSERT INTO library.""BaseItemProviders"" (""ItemId"", ""ProviderId"", ""ProviderValue"") - VALUES ({entity.Id}, {provider.ProviderId}, {provider.ProviderValue}) - ON CONFLICT (""ItemId"", ""ProviderId"") - DO UPDATE SET ""ProviderValue"" = EXCLUDED.""ProviderValue""", - cancellationToken); - -// CRITICAL: Clear navigation property -entity.Provider = null; -``` - -### Remote Backup Support - -Removed artificial restriction that disabled backups for remote databases: - -```csharp -// Before: Only localhost -if (IsLocalHost(currentHost) && configurationManager is not null) - -// After: Local AND remote -if (configurationManager is not null) -``` - -**Requirements:** -- PostgreSQL client binaries (`pg_dump`, `pg_restore`) -- Must be in PATH or specified in BackupOptions -- Network connectivity to remote server - -## Documentation - -Comprehensive documentation created: - -- **[COMPLETE-SESSION-SUMMARY.md](docs/COMPLETE-SESSION-SUMMARY.md)** - Complete list of all fixes -- **[database-configuration-examples.md](docs/database-configuration-examples.md)** - All configuration options -- **[remote-postgresql-backup-support.md](docs/remote-postgresql-backup-support.md)** - Remote backup guide -- **[library-monitor-delay-configuration.md](docs/library-monitor-delay-configuration.md)** - File monitoring configuration -- **[ef-core-tracking-conflict-fix.md](docs/ef-core-tracking-conflict-fix.md)** - EF Core tracking issues explained - -Plus SQL performance scripts: -- `sql/add-performance-indexes.sql` -- `sql/monitor-query-performance.sql` - -## Recommendations - -### Immediate Actions (Required) -1. Add `command-timeout` configuration -2. Run performance indexes SQL script -3. Install PostgreSQL client tools (if using backups) -4. Restart Jellyfin - -### Short Term (Next Week) -1. Monitor deadlock frequency -2. Verify no regressions in library scanning -3. Test backup/restore functionality - -### Long Term (Next Release) -1. Upgrade to stable .NET when available -2. Consider implementing advisory locks for cleanup operations -3. Revisit query optimization with stable EF Core - -## Compatibility - -- **Tested on:** .NET 11 Preview, PostgreSQL 17 -- **Backward Compatible:** Yes -- **Database Migration Required:** No -- **Configuration Changes Required:** Recommended (see Migration Guide) - -## Related Issues - -This PR resolves issues related to: -- Concurrent metadata refresh operations -- Remote database backup functionality -- Query timeout errors on large libraries -- Authentication error logging clarity -- Database deadlock handling - -## Credits - -**Session Date:** 2026-03-03 -**Testing Environment:** .NET 11 Preview, PostgreSQL 17 -**Total Development Time:** Multiple iterations to achieve production quality - ---- - -## For Reviewers - -### Critical Files to Review -1. `Jellyfin.Server.Implementations/Item/BaseItemRepository.cs` - **Navigation property clearing is critical** -2. `src/Jellyfin.Database/Jellyfin.Database.Providers.Postgres/PostgresDatabaseProvider.cs` - Backup logic changes -3. `MediaBrowser.Model/Configuration/ServerConfiguration.cs` - New validation logic - -### Test Scenarios -- [ ] Concurrent metadata refreshes on same item -- [ ] Remote PostgreSQL backup/restore -- [ ] LibraryMonitorDelay validation (try setting to 10, should enforce 30) -- [ ] Query performance with indexes - -### Documentation Quality -All changes are thoroughly documented with: -- ✅ Problem description -- ✅ Solution explanation -- ✅ Configuration examples -- ✅ Troubleshooting guides -- ✅ Code comments in critical sections - ---- - -**This PR makes Jellyfin PostgreSQL production-ready! 🎉** diff --git a/docs/PR-DESCRIPTION-SHORT.md b/docs/PR-DESCRIPTION-SHORT.md deleted file mode 100644 index 21652034..00000000 --- a/docs/PR-DESCRIPTION-SHORT.md +++ /dev/null @@ -1,115 +0,0 @@ -# PostgreSQL Error Fixes - Production Ready - -## Summary - -Resolves 8 critical issues and adds 3 enhancements to make Jellyfin PostgreSQL production-ready for high-concurrency environments. - -## Key Fixes - -1. ✅ **Constraint Violation (Critical)** - Fixed duplicate key errors during concurrent metadata refreshes using atomic SQL UPSERT with navigation property clearing -2. ✅ **Remote Backup Support** - Enabled backups/restores for remote PostgreSQL servers (not just localhost) -3. ✅ **Query Timeouts** - Added configurable command timeout (default 120s) + performance indexes -4. ✅ **Authentication Errors** - Changed auth failures from errors to warnings (80% log noise reduction) -5. ✅ **Database Deadlocks** - Clear warning messages with automatic retry indication -6. ✅ **SyncPlay Auth** - Validate empty GUIDs before processing -7. ✅ **SQLite Migration** - Skip SQLite-specific migrations on PostgreSQL -8. ✅ **StyleCop** - Suppressed SA1137 warnings on pre-existing code - -## Enhancements - -1. **Configurable Backup Disable** - Option to disable built-in backups (`disable-backups=true`) -2. **LibraryMonitorDelay Configurable** - File monitoring delay now configurable (minimum 30s, default 60s) -3. **Comprehensive Documentation** - 21 documentation files with complete guides - -## Critical Fix Details - -**Most Complex Fix: BaseItemProviders Constraint Violation** - -Took 4 iterations to solve: -- Iteration 1: Better error messages -- Iteration 2: EF Core UPSERT (tracking conflicts) -- Iteration 3: Raw SQL with ON CONFLICT (race conditions) -- **Iteration 4:** Raw SQL + **Navigation property clearing** ✅ - -**The key insight:** After using raw SQL, must clear `entity.Provider = null` to prevent EF Core from re-tracking and re-inserting. - -## Configuration Required - -### Recommended (Add to database.xml) -```xml - - command-timeout - 120 - -``` - -### Optional: Disable Backups -```xml - - disable-backups - True - -``` - -### Optional: Adjust File Monitoring -```xml -60 -``` - -### Performance Indexes (Run Once) -```bash -psql -U postgres -d jellyfin_db -f sql/add-performance-indexes.sql -``` - -## Files Modified - -**Code:** 8 files -- Jellyfin.Server/Migrations/JellyfinMigrationService.cs -- Jellyfin.Api/Auth/SyncPlayAccessPolicy/SyncPlayAccessHandler.cs -- Jellyfin.Api/Middleware/ExceptionMiddleware.cs -- Jellyfin.Server.Implementations/Item/BaseItemRepository.cs (Critical) -- src/Jellyfin.Database/Jellyfin.Database.Implementations/JellyfinDbContext.cs -- src/Jellyfin.Database/Jellyfin.Database.Providers.Postgres/PostgresDatabaseProvider.cs -- MediaBrowser.Model/Configuration/ServerConfiguration.cs (NEW validation) -- .editorconfig - -**Documentation:** 21 files (see docs/) - -## Performance Impact - -| Metric | Before | After | -|--------|--------|-------| -| Query Timeout | 30s (fails) | 2-10s ✅ | -| Metadata Refresh Success | ~60% | 100% ✅ | -| Deadlock Auto-Recovery | Unclear | 95-99% ✅ | -| Log Noise | High | -80% ✅ | - -## Testing - -✅ Build successful -✅ No breaking changes -✅ All error scenarios tested -✅ Concurrent operations verified - -## Breaking Changes - -**None** - All changes are backward compatible. - -## Documentation - -Complete documentation in `docs/`: -- COMPLETE-SESSION-SUMMARY.md - Full details -- database-configuration-examples.md - Config reference -- remote-postgresql-backup-support.md - Backup guide -- library-monitor-delay-configuration.md - File monitoring -- Plus 17+ other guides - -## Tested On - -- .NET 11 Preview -- PostgreSQL 17 -- Windows (local) + Remote PostgreSQL server - ---- - -**This PR makes Jellyfin PostgreSQL production-ready for enterprise use! 🎉** diff --git a/docs/PR-QUICK-COPY.md b/docs/PR-QUICK-COPY.md deleted file mode 100644 index 550212b4..00000000 --- a/docs/PR-QUICK-COPY.md +++ /dev/null @@ -1,84 +0,0 @@ -# PR Title - -``` -PostgreSQL: Fix 8 critical issues + remote backup support + configurable monitoring -``` - -# PR Description (Short Version) - -## What This PR Does - -Fixes **8 critical production issues** in the PostgreSQL implementation: - -1. ✅ **Constraint violations** during concurrent metadata refreshes (atomic SQL UPSERT + navigation clearing) -2. ✅ **Remote backup support** (removed localhost restriction) -3. ✅ **Query timeouts** (configurable timeout + performance indexes) -4. ✅ **Auth error logging** (warnings instead of errors, -80% log noise) -5. ✅ **Deadlock handling** (clear messages with auto-retry indication) -6. ✅ **SyncPlay auth** (validate empty GUIDs) -7. ✅ **SQLite migration** (skip on PostgreSQL) -8. ✅ **StyleCop** (suppress pre-existing warnings) - -**Plus 3 enhancements:** -- Configurable backup disable option -- LibraryMonitorDelay now configurable (30s minimum) -- Comprehensive documentation (21 files) - -## Key Technical Achievement - -**Fixed the most challenging issue:** BaseItemProviders constraint violations - -Took 4 iterations to solve correctly: -- Used raw SQL with `ON CONFLICT` for atomic UPSERT -- **Critical insight:** Must clear `entity.Provider = null` after raw SQL to prevent EF Core from re-tracking - -## Impact - -- **Performance:** 3-15x faster queries -- **Reliability:** 100% metadata refresh success (was ~60%) -- **Logs:** 80% reduction in noise -- **Features:** Remote backups now work - -## Configuration Needed - -```xml - - command-timeout - 120 - -``` - -Then run: `psql -U postgres -d jellyfin_db -f sql/add-performance-indexes.sql` - -## Files - -- **Code:** 8 files -- **Docs:** 21 files -- **Breaking:** None - -See [COMPLETE-SESSION-SUMMARY.md](docs/COMPLETE-SESSION-SUMMARY.md) for full details. - ---- - -**Makes PostgreSQL production-ready! 🚀** - -## Git Commit Message - -``` -fix: PostgreSQL production fixes - constraint violations, remote backups, performance - -- Fix: Atomic UPSERT for BaseItemProviders (ON CONFLICT + nav clearing) -- Fix: Remote PostgreSQL backup support (remove localhost restriction) -- Fix: Configurable query timeout (default 120s) + performance indexes -- Fix: Auth errors now warnings (SyncPlay, token validation) -- Fix: Deadlock clear warning messages -- Fix: Skip SQLite migrations on PostgreSQL -- Add: Configurable backup disable option -- Add: LibraryMonitorDelay validation (30s minimum) -- Docs: 21 comprehensive documentation files - -Performance: 3-15x faster queries, 100% metadata refresh success -Breaking: None (backward compatible) - -Tested: .NET 11 Preview, PostgreSQL 17 -``` diff --git a/docs/PR_DESCRIPTION.md b/docs/PR_DESCRIPTION.md deleted file mode 100644 index acc043ee..00000000 --- a/docs/PR_DESCRIPTION.md +++ /dev/null @@ -1,316 +0,0 @@ -# Pull Request: PostgreSQL Integration, Windows Installer, and Documentation Overhaul - -## 🎯 Overview - -This PR completes the PostgreSQL integration for Jellyfin with comprehensive Windows installer support, centralized build output, OS-specific configuration, and a complete documentation overhaul. - -## 🚀 What's New - -### 1. **Complete Documentation Overhaul** 📚 -- Rewrote **README.md** to highlight PostgreSQL features, Windows installer, and migration guides -- Moved all markdown files to `docs/` folder for better organization (30+ files organized) -- Created comprehensive documentation index with quick start and detailed guides -- Added `README_GENERATION.md` and `DOCUMENTATION_ORGANIZATION.md` for maintenance -- Preserved original README as `README.original.md` -- Clear platform-specific instructions (Windows/Linux/macOS) - -### 2. **Professional Windows Installer** 💿 -- **Inno Setup script** (`jellyfin-setup.iss`) with full wizard support -- **PowerShell build automation** (`build-installer.ps1`) for easy installer creation -- **Features:** - - Windows Service installation - - Firewall rules configuration - - PostgreSQL connection wizard - - .NET runtime verification - - Clean uninstaller -- **Comprehensive documentation:** - - `INSTALLER_QUICK_START.md` - 5-minute guide - - `INSTALLER_GUIDE.md` - Complete reference with WiX, MSIX options - - `BUILD_INSTALLER_FIXED.md` - Build script usage - -### 3. **Centralized Build Output** 🔨 -- All DLLs now output to `lib\[Configuration]\[TargetFramework]\` at repository root -- Configured via `Directory.Build.props` -- **Benefits:** - - Single location for all build artifacts - - Easier deployment and packaging - - No duplicate dependencies - - Faster builds -- Documentation: `CENTRALIZED_LIB_FOLDER.md` - -### 4. **OS-Specific Startup Configuration** ⚙️ -- Auto-generates `startup.json` with OS-appropriate defaults on first run -- **Platform defaults:** - - **Windows:** `C:/ProgramData/jellyfin` - - **Linux:** `/var/lib/jellyfin`, `/etc/jellyfin` - - **macOS:** `~/Library/Application Support/jellyfin` -- Removes null/example config - immediately usable -- Configuration priority: CLI args → Environment vars → startup.json → Built-in defaults -- **Documentation:** - - `OS_SPECIFIC_STARTUP_CONFIG.md` - - `STARTUP_JSON_VERIFICATION.md` - - `STARTUP_JSON_FIX.md` - -### 5. **PostgreSQL Migration Improvements** 🗄️ -- Assign all tables to correct PostgreSQL schemas in EF Core migrations -- Fix identifier quoting (SQL Server brackets → PostgreSQL double quotes) -- Use InsertData for placeholder BaseItems row (no raw SQL) -- **Auto-recovery:** Handles 42P07 errors (table exists) -- Added `RecordMigrationAsAppliedAsync` for manual migration history -- Improved migration logging and error handling -- **Documentation:** - - `POSTGRESQL_MIGRATION_COMPLETE.md` - - `MIGRATION_RECOVERY_FIX.md` - - `SQLITE_MIGRATION_FILTERING_FIX.md` -- Idempotent, production-ready SQL migration scripts -- PowerShell script for automated migration verification - -### 6. **Platform Configuration Templates** 📋 -- Added Linux/Windows startup config templates in `Resources/Configuration/` -- FHS-compliant default paths -- Platform-specific README with usage instructions -- Improved portability and cross-platform consistency - -### 7. **Build and Deployment Improvements** 🚢 -- Enhanced publish profiles with platform targeting -- Clean deploy: deletes existing files before publish -- Updated `.gitignore`: - - Excludes `lib/` (build output) - - Excludes `installer-output/` - - Excludes all `PublishProfiles/` folders (machine-specific) - - Cleaned up tracked publish profile XMLs -- Switched to relative paths for improved portability - ---- - -## 📊 Changes Summary - -### Files Added/Created -- `build-installer.ps1` - PowerShell installer build script -- `jellyfin-setup.iss` - Inno Setup installer script -- `jellyfin.ico` - Application icon -- `docs/INSTALLER_QUICK_START.md` - 5-minute installer guide -- `docs/INSTALLER_GUIDE.md` - Complete installer documentation -- `docs/BUILD_INSTALLER_FIXED.md` - Build script usage -- `docs/CENTRALIZED_LIB_FOLDER.md` - Build output documentation -- `docs/OS_SPECIFIC_STARTUP_CONFIG.md` - OS configuration guide -- `docs/STARTUP_JSON_VERIFICATION.md` - Configuration loading details -- `docs/STARTUP_JSON_FIX.md` - Fixing null value issues -- `docs/GITIGNORE_PUBLISHPROFILES.md` - GitIgnore documentation -- `docs/DOCUMENTATION_ORGANIZATION.md` - Doc organization summary -- `docs/README_GENERATION.md` - README generation process -- `Jellyfin.Server/Resources/Configuration/startup.*.json` - Platform templates - -### Files Modified -- `README.md` - Complete rewrite with PostgreSQL focus -- `Directory.Build.props` - Centralized build output configuration -- `.gitignore` - Updated exclusions for lib, installer-output, PublishProfiles -- `Jellyfin.Server/Helpers/StartupHelpers.cs` - OS-specific config generation -- EF Core migrations - PostgreSQL schema and quoting fixes -- Publish profiles - Platform targeting and clean deploy - -### Files Moved -- 30+ documentation files → `docs/` folder -- All README links updated to point to `docs/` - -### Files Removed -- Old `Jellyfin.Server/startup.json` (now generated at runtime) -- Obsolete Windows publish profiles -- Tracked PublishProfiles XML files - ---- - -## 🎯 Migration Guide - -### From SQLite to PostgreSQL - -```bash -# 1. Backup SQLite database -cp jellyfin.db jellyfin-backup.db - -# 2. Install PostgreSQL 12+ -winget install PostgreSQL.PostgreSQL - -# 3. Create database -psql -U postgres -CREATE USER jellyfin WITH PASSWORD 'your_password'; -CREATE DATABASE jellyfin OWNER jellyfin; -\q - -# 4. Update startup.json -{ - "DatabaseProvider": "Postgres", - "ConnectionStrings": { - "DefaultConnection": "Host=localhost;Database=jellyfin;Username=jellyfin;Password=your_password" - } -} - -# 5. Run migration -dotnet run --project Jellyfin.Server -- --migrate-database -``` - -See `docs/POSTGRESQL_MIGRATION_COMPLETE.md` for details. - ---- - -## 🔨 Building and Installation - -### Quick Build -```bash -git clone https://gitea.wpjones.com/wjones/pgsql-jellyfin.git -cd pgsql-jellyfin -dotnet build --configuration Release -cd lib/Release/net11.0 -dotnet jellyfin.dll -``` - -### Create Windows Installer -```powershell -# Install Inno Setup -winget install JRSoftware.InnoSetup - -# Build installer -.\build-installer.ps1 - -# Result: installer-output\JellyfinSetup-PostgreSQL-11.0.0.exe -``` - ---- - -## 🧪 Testing - -### Tested Scenarios -- ✅ Fresh install on Windows -- ✅ Migration from SQLite to PostgreSQL -- ✅ OS-specific configuration generation -- ✅ Windows Service installation -- ✅ Firewall rules creation -- ✅ Build output to lib folder -- ✅ Documentation links and navigation - -### Tested Platforms -- ✅ Windows 10/11 -- ✅ Linux (Ubuntu 22.04) -- ✅ PostgreSQL 12, 14, 15, 16, 17, 18 - ---- - -## 📝 Documentation - -All documentation is now in the `docs/` folder with a complete index in README.md: - -### Configuration -- OS_SPECIFIC_STARTUP_CONFIG.md -- STARTUP_JSON_VERIFICATION.md -- STARTUP_JSON_FIX.md - -### PostgreSQL -- QUICKSTART_POSTGRESQL.md -- POSTGRESQL_MIGRATION_COMPLETE.md -- POSTGRESQL_TROUBLESHOOTING.md - -### Installation -- INSTALLER_QUICK_START.md -- INSTALLER_GUIDE.md -- CENTRALIZED_LIB_FOLDER.md -- BUILD_INSTALLER_FIXED.md - -### Backup & Recovery -- POSTGRES_BACKUP_IMPLEMENTATION.md -- POSTGRESQL_BACKUP_ANALYSIS.md - -### Project Status -- PROJECT_COMPLETION.md -- POC_SUMMARY_REPORT.md - -[View All Documentation →](./docs/) - ---- - -## ⚠️ Breaking Changes - -**None!** All changes are backward compatible: -- Existing `startup.json` files are preserved -- SQLite users can continue using SQLite -- Migration to PostgreSQL is optional -- Default behavior unchanged for existing installations - ---- - -## 🎉 Benefits - -### For Users -- ✅ Professional Windows installer with wizard -- ✅ Automatic OS-specific configuration -- ✅ Better performance with large media libraries -- ✅ Enterprise-grade database backend -- ✅ Easy migration from SQLite - -### For Developers -- ✅ Centralized build output (lib folder) -- ✅ Comprehensive documentation -- ✅ Easy installer creation (5 minutes) -- ✅ Clean repository structure -- ✅ Better cross-platform support - -### For System Admins -- ✅ FHS-compliant paths on Linux -- ✅ Windows Service support -- ✅ Professional backup solutions -- ✅ Database replication and clustering support - ---- - -## 🔄 Commits Included - -1. **Docs: overhaul README, centralize docs, update .gitignore** - Documentation reorganization -2. **Add Windows installer scripts, docs, and startup.json fixes** - Installer infrastructure -3. **Centralize build output and generate OS-specific startup.json** - Build improvements -4. **Platform config templates & Postgres migration recovery** - Configuration and migration -5. **PostgreSQL migration: schema fixes, docs, and tooling** - Database migrations -6. **Update publish profiles and .gitignore for Windows build** - Build configuration -7. **Update publish profile and web dir config for portability** - Path improvements - ---- - -## 📞 Support - -- 📚 [Documentation](./docs/) -- 🐛 [Report Bug](https://gitea.wpjones.com/wjones/pgsql-jellyfin/issues) -- 💡 [Request Feature](https://gitea.wpjones.com/wjones/pgsql-jellyfin/issues) - ---- - -## ✅ Checklist - -- [x] Code compiles without errors -- [x] All tests pass -- [x] Documentation updated and comprehensive -- [x] README.md reflects all changes -- [x] .gitignore updated appropriately -- [x] Migration scripts tested -- [x] Windows installer tested -- [x] Cross-platform compatibility verified -- [x] No breaking changes introduced - ---- - -## 🎯 Ready to Merge - -This PR represents a major milestone for the PostgreSQL-enabled Jellyfin fork: -- Complete documentation overhaul with 30+ organized files -- Professional Windows installer with service support -- Centralized build output for easier deployment -- OS-specific configuration that "just works" -- Robust PostgreSQL migration with auto-recovery -- Production-ready, tested, and documented - -**Recommended for merge into main branch.** - ---- - -**Pull Request Type:** Feature + Documentation + Build Improvement -**Target Branch:** main -**Source Branch:** pgsql_testing_branch -**Reviewer:** @maintainers -**Priority:** High diff --git a/docs/PR_DESCRIPTION_SHORT.md b/docs/PR_DESCRIPTION_SHORT.md deleted file mode 100644 index 546a15e4..00000000 --- a/docs/PR_DESCRIPTION_SHORT.md +++ /dev/null @@ -1,94 +0,0 @@ -# PostgreSQL Integration + Windows Installer + Documentation Overhaul - -## Summary - -Complete PostgreSQL integration for Jellyfin with professional Windows installer, centralized build output, OS-specific configuration, and comprehensive documentation reorganization. - -## Key Features - -✅ **Windows Installer** - Inno Setup script with service installation, firewall rules, and PostgreSQL wizard -✅ **Centralized Build** - All DLLs output to `lib/[Configuration]/` folder -✅ **OS-Specific Config** - Auto-generates `startup.json` with platform-appropriate defaults -✅ **PostgreSQL Migration** - Robust migration with auto-recovery and comprehensive docs -✅ **Documentation** - 30+ files organized in `docs/` folder with complete index - -## What's Included - -### Documentation (30+ files) -- Rewrote README.md with PostgreSQL focus and quick start -- Moved all .md files to docs/ folder -- Added installer guides, migration guides, troubleshooting -- Complete navigation and organization - -### Windows Installer -- `build-installer.ps1` - PowerShell automation -- `jellyfin-setup.iss` - Inno Setup script -- Service installation, firewall setup, PostgreSQL wizard -- 5-minute quick start guide - -### Build System -- Centralized output: `lib/[Configuration]/[TargetFramework]/` -- Updated Directory.Build.props -- Clean deployment with publish profiles -- Updated .gitignore (lib, installer-output, PublishProfiles) - -### Configuration -- OS-specific startup.json generation (Windows/Linux/macOS) -- Platform templates in Resources/Configuration/ -- Priority: CLI → Env → startup.json → Defaults -- FHS-compliant paths on Linux - -### PostgreSQL -- Schema fixes for PostgreSQL in EF migrations -- Identifier quoting (brackets → double quotes) -- Auto-recovery from migration errors -- Comprehensive migration documentation -- Production-ready SQL scripts - -## Testing - -✅ Fresh Windows install -✅ SQLite → PostgreSQL migration -✅ Windows Service installation -✅ Cross-platform configuration -✅ Build output verification - -## Breaking Changes - -**None!** All changes are backward compatible. - -## Commits (7) - -1. Docs: overhaul README, centralize docs, update .gitignore -2. Add Windows installer scripts, docs, and startup.json fixes -3. Centralize build output and generate OS-specific startup.json -4. Platform config templates & Postgres migration recovery -5. PostgreSQL migration: schema fixes, docs, and tooling -6. Update publish profiles and .gitignore for Windows build -7. Update publish profile and web dir config for portability - -## Quick Start - -```bash -# Build -dotnet build --configuration Release -cd lib/Release/net11.0 -dotnet jellyfin.dll - -# Create installer (Windows) -winget install JRSoftware.InnoSetup -.\build-installer.ps1 -``` - -## Documentation - -- [Quick Start](./docs/QUICKSTART_POSTGRESQL.md) -- [Installer Guide](./docs/INSTALLER_QUICK_START.md) -- [Migration Guide](./docs/POSTGRESQL_MIGRATION_COMPLETE.md) -- [All Docs](./docs/) - ---- - -**Ready for Review** ✅ -Target: main | Source: pgsql_testing_branch -Type: Feature + Documentation + Build diff --git a/editorconfig_new.txt b/editorconfig_new.txt deleted file mode 100644 index f7801d30..00000000 --- a/editorconfig_new.txt +++ /dev/null @@ -1,28 +0,0 @@ -# EditorConfig for MediaBrowser.Model -# https://EditorConfig.org - -root = true - -[*] -charset = utf-8 -insert_final_newline = true -trim_trailing_whitespace = true - -[*.cs] -indent_size = 4 -indent_style = space -dotnet_sort_system_directives_first = true -dotnet_separate_import_directive_groups = false - -# StyleCop Analyzer Rules - Disabled for project consistency -dotnet_diagnostic.SA1101.severity = none -dotnet_diagnostic.SA1309.severity = none -dotnet_diagnostic.SA1204.severity = none -dotnet_diagnostic.SA1202.severity = none -dotnet_diagnostic.SA1135.severity = none -dotnet_diagnostic.SA1600.severity = suggestion - -# StyleCop Analyzer Rules - Keep enabled -dotnet_diagnostic.SA1413.severity = warning -dotnet_diagnostic.SA1515.severity = warning -dotnet_diagnostic.SA1518.severity = warning diff --git a/Add-All-Indexes.bat b/scripts/Add-All-Indexes.bat similarity index 100% rename from Add-All-Indexes.bat rename to scripts/Add-All-Indexes.bat diff --git a/Add-Base-Indexes.bat b/scripts/Add-Base-Indexes.bat similarity index 100% rename from Add-Base-Indexes.bat rename to scripts/Add-Base-Indexes.bat diff --git a/Add-Indexes-Quick.bat b/scripts/Add-Indexes-Quick.bat similarity index 100% rename from Add-Indexes-Quick.bat rename to scripts/Add-Indexes-Quick.bat diff --git a/Add-Indexes-Quick.ps1 b/scripts/Add-Indexes-Quick.ps1 similarity index 100% rename from Add-Indexes-Quick.ps1 rename to scripts/Add-Indexes-Quick.ps1 diff --git a/Fix-ItemValues-Performance.ps1 b/scripts/Fix-ItemValues-Performance.ps1 similarity index 100% rename from Fix-ItemValues-Performance.ps1 rename to scripts/Fix-ItemValues-Performance.ps1 diff --git a/build-installer.ps1 b/scripts/build-installer.ps1 similarity index 100% rename from build-installer.ps1 rename to scripts/build-installer.ps1 diff --git a/copy-sql-files.ps1 b/scripts/copy-sql-files.ps1 similarity index 100% rename from copy-sql-files.ps1 rename to scripts/copy-sql-files.ps1 diff --git a/db-config.ps1 b/scripts/db-config.ps1 similarity index 100% rename from db-config.ps1 rename to scripts/db-config.ps1 diff --git a/db-quick.ps1 b/scripts/db-quick.ps1 similarity index 100% rename from db-quick.ps1 rename to scripts/db-quick.ps1 diff --git a/publish-with-sql.ps1 b/scripts/publish-with-sql.ps1 similarity index 100% rename from publish-with-sql.ps1 rename to scripts/publish-with-sql.ps1 diff --git a/rebuild-solution.ps1 b/scripts/rebuild-solution.ps1 similarity index 100% rename from rebuild-solution.ps1 rename to scripts/rebuild-solution.ps1 diff --git a/remove-sqlite.ps1 b/scripts/remove-sqlite.ps1 similarity index 100% rename from remove-sqlite.ps1 rename to scripts/remove-sqlite.ps1