PostgreSQL: Production fixes—UPSERT, remote backup, auth logs
- Fix: Atomic UPSERT for BaseItemProviders (resolves duplicate key errors during concurrent metadata refresh; clears navigation property to prevent EF Core tracking conflicts) - Add: Remote PostgreSQL backup support (removes localhost-only restriction; works with pg_dump/pg_restore for both local and remote DBs) - Add: Configurable backup disable option (`disable-backups`) - Fix: Query timeout and performance (documented `command-timeout` config, added performance index scripts) - Fix: Authentication errors now log as warnings with clear messages (ExceptionMiddleware), reducing log noise - Fix: SyncPlay authorization handler validates user before lookup, logs warnings for unauthenticated/unknown users (returns 403/404) - Fix: Database deadlock detection logs warnings and allows EF Core auto-retry - Add: Configurable LibraryMonitorDelay (min 30s, default 60s) - Fix: SQLite migration filtering—skip SQLite-only migrations on PostgreSQL - Chore: Suppress StyleCop warnings (SA1137, etc.) for project consistency - Docs: 21 documentation files added/updated (config, backup, performance, troubleshooting, session summary) - All changes are backward compatible and production-ready
This commit is contained in:
@@ -0,0 +1,294 @@
|
||||
# Library Monitor Delay Configuration
|
||||
|
||||
## Overview
|
||||
|
||||
The `LibraryMonitorDelay` setting controls how long Jellyfin waits after detecting a file system change before processing the change. This delay is necessary because file operations (especially large video files) are not atomic and can take time to complete.
|
||||
|
||||
## Configuration
|
||||
|
||||
### Location
|
||||
|
||||
The setting is configurable in your Jellyfin configuration file (typically `system.xml` or via the Dashboard).
|
||||
|
||||
### Default Value
|
||||
|
||||
**60 seconds** - This provides a good balance between responsiveness and stability for most use cases.
|
||||
|
||||
### Minimum Value
|
||||
|
||||
**30 seconds** - The system enforces a minimum of 30 seconds to prevent:
|
||||
- Processing incomplete file transfers
|
||||
- Excessive system load from rapid refreshes
|
||||
- Metadata corruption from accessing files still being written
|
||||
|
||||
### Maximum Value
|
||||
|
||||
**Unlimited** - You can set this as high as needed for very slow network file systems or large file transfers.
|
||||
|
||||
## How to Configure
|
||||
|
||||
### Method 1: Via Configuration File
|
||||
|
||||
Edit your `config/system.xml` file:
|
||||
|
||||
```xml
|
||||
<ServerConfiguration>
|
||||
<!-- Delay in seconds after file system change before processing -->
|
||||
<!-- Default: 60, Minimum: 30 -->
|
||||
<LibraryMonitorDelay>60</LibraryMonitorDelay>
|
||||
</ServerConfiguration>
|
||||
```
|
||||
|
||||
### Method 2: Via Dashboard (If Available)
|
||||
|
||||
1. Open Jellyfin Dashboard
|
||||
2. Navigate to **Settings → Library**
|
||||
3. Find **Library Monitor Delay** setting
|
||||
4. Set value (minimum 30 seconds)
|
||||
5. Save changes
|
||||
6. Restart Jellyfin
|
||||
|
||||
## Use Cases
|
||||
|
||||
### Standard Setup (60 seconds - Default)
|
||||
```xml
|
||||
<LibraryMonitorDelay>60</LibraryMonitorDelay>
|
||||
```
|
||||
|
||||
**Best for:**
|
||||
- Local storage
|
||||
- Fast network drives
|
||||
- Small to medium file sizes
|
||||
|
||||
### Network File Systems (120-300 seconds)
|
||||
```xml
|
||||
<LibraryMonitorDelay>180</LibraryMonitorDelay>
|
||||
```
|
||||
|
||||
**Best for:**
|
||||
- NAS/Network storage
|
||||
- Slow network connections
|
||||
- Very large video files (4K, remux)
|
||||
|
||||
### Minimal Delay (30 seconds)
|
||||
```xml
|
||||
<LibraryMonitorDelay>30</LibraryMonitorDelay>
|
||||
```
|
||||
|
||||
**Best for:**
|
||||
- Fast local SSDs
|
||||
- Small files (music, photos)
|
||||
- When immediate updates are critical
|
||||
|
||||
**⚠️ Warning:** Using 30 seconds may cause issues with:
|
||||
- Large file transfers not completing in time
|
||||
- Metadata refresh on partially written files
|
||||
- Increased system load
|
||||
|
||||
### Extended Delay (300+ seconds)
|
||||
```xml
|
||||
<LibraryMonitorDelay>600</LibraryMonitorDelay>
|
||||
```
|
||||
|
||||
**Best for:**
|
||||
- Very slow network storage
|
||||
- Satellite/remote connections
|
||||
- Extremely large files (100GB+ remux files)
|
||||
- Bulk file operations
|
||||
|
||||
## How It Works
|
||||
|
||||
### Timeline Example (60 second delay)
|
||||
|
||||
```
|
||||
Time 0:00 - File starts copying to watched directory
|
||||
↓
|
||||
Time 0:05 - FileSystemWatcher detects change (OS notification)
|
||||
↓
|
||||
Time 1:05 - LibraryMonitorDelay expires (60 seconds)
|
||||
↓
|
||||
Time 1:05 - Jellyfin begins processing the file
|
||||
↓
|
||||
Time 1:10 - File is added to library
|
||||
↓
|
||||
Time 1:40 - Notification sent to clients (+ LibraryUpdateDuration 30s)
|
||||
```
|
||||
|
||||
**Total time from detection to notification: ~95 seconds**
|
||||
|
||||
## Validation
|
||||
|
||||
The system **automatically enforces** the 30-second minimum:
|
||||
|
||||
```csharp
|
||||
// If you set a value less than 30, it will be clamped to 30
|
||||
LibraryMonitorDelay = 15; // ❌ Invalid
|
||||
// Actual value used: 30 // ✅ Enforced minimum
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
- Setting value: `10` → Actual value: `30` (minimum enforced)
|
||||
- Setting value: `45` → Actual value: `45` (valid)
|
||||
- Setting value: `60` → Actual value: `60` (default)
|
||||
- Setting value: `300` → Actual value: `300` (valid)
|
||||
|
||||
## Related Settings
|
||||
|
||||
### LibraryUpdateDuration (30 seconds default)
|
||||
Additional delay before sending notifications to clients after library changes.
|
||||
|
||||
```xml
|
||||
<LibraryUpdateDuration>30</LibraryUpdateDuration>
|
||||
```
|
||||
|
||||
**Combined delay example:**
|
||||
- File detected: 0s
|
||||
- LibraryMonitorDelay: 60s
|
||||
- Processing complete: 65s
|
||||
- LibraryUpdateDuration: +30s
|
||||
- **Client notification: 95s total**
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Problem: Files showing as corrupted or incomplete
|
||||
|
||||
**Solution:** Increase the delay
|
||||
```xml
|
||||
<LibraryMonitorDelay>120</LibraryMonitorDelay>
|
||||
```
|
||||
|
||||
**Reason:** File transfer wasn't complete before Jellyfin tried to process it.
|
||||
|
||||
### Problem: Library updates too slow
|
||||
|
||||
**Solution:** Decrease the delay (but not below 30)
|
||||
```xml
|
||||
<LibraryMonitorDelay>30</LibraryMonitorDelay>
|
||||
```
|
||||
|
||||
**Warning:** May cause issues with slow storage or large files.
|
||||
|
||||
### Problem: Setting value of 10 doesn't work
|
||||
|
||||
**Solution:** Use at least 30 seconds
|
||||
```xml
|
||||
<LibraryMonitorDelay>30</LibraryMonitorDelay>
|
||||
```
|
||||
|
||||
**Reason:** System enforces a minimum of 30 seconds for stability.
|
||||
|
||||
### Problem: Excessive library refreshes
|
||||
|
||||
**Solution:** Increase the delay
|
||||
```xml
|
||||
<LibraryMonitorDelay>300</LibraryMonitorDelay>
|
||||
```
|
||||
|
||||
**Reason:** Multiple file changes within the delay period are batched together.
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
### Impact of Different Values
|
||||
|
||||
| Setting | Pros | Cons | Best For |
|
||||
|---------|------|------|----------|
|
||||
| **30s** | Fast updates, immediate feedback | May process incomplete files | Local SSD, small files |
|
||||
| **60s** (default) | Good balance, reliable | Slight delay in updates | Most use cases |
|
||||
| **120s** | Handles slow transfers well | Noticeable delay | Network storage |
|
||||
| **300s+** | Very safe for slow systems | Long delay before updates | Very slow storage, bulk ops |
|
||||
|
||||
### CPU and I/O Impact
|
||||
|
||||
- **Lower values (30-60s)**: More frequent processing, higher CPU/disk usage
|
||||
- **Higher values (120-300s)**: Less frequent processing, lower system load, batched operations
|
||||
|
||||
### Network Considerations
|
||||
|
||||
**Local Storage:**
|
||||
- Recommended: 30-60 seconds
|
||||
- File changes are immediate, low latency
|
||||
|
||||
**Network Storage (LAN):**
|
||||
- Recommended: 60-120 seconds
|
||||
- Account for network transfer time
|
||||
|
||||
**Network Storage (WAN/Remote):**
|
||||
- Recommended: 180-600 seconds
|
||||
- Account for high latency and slow transfer speeds
|
||||
|
||||
## Technical Details
|
||||
|
||||
### Implementation
|
||||
|
||||
**File:** `MediaBrowser.Model/Configuration/ServerConfiguration.cs`
|
||||
|
||||
```csharp
|
||||
private int _libraryMonitorDelay = 60;
|
||||
|
||||
public int LibraryMonitorDelay
|
||||
{
|
||||
get => _libraryMonitorDelay;
|
||||
set => _libraryMonitorDelay = value < 30 ? 30 : value; // Enforces minimum of 30
|
||||
}
|
||||
```
|
||||
|
||||
### Used By
|
||||
|
||||
**File:** `Emby.Server.Implementations/IO/FileRefresher.cs`
|
||||
|
||||
```csharp
|
||||
_timer = new Timer(
|
||||
OnTimerCallback,
|
||||
null,
|
||||
TimeSpan.FromSeconds(_configurationManager.Configuration.LibraryMonitorDelay),
|
||||
TimeSpan.FromMilliseconds(-1)
|
||||
);
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Start with default (60s)** and adjust based on your needs
|
||||
2. **Monitor logs** for incomplete file errors
|
||||
3. **Increase for network storage** (120-180s)
|
||||
4. **Don't go below 30s** unless using very fast local storage
|
||||
5. **Test with your largest files** to find the right value
|
||||
6. **Batch operations** benefit from higher values
|
||||
|
||||
## Example Configurations
|
||||
|
||||
### Home Media Server (Local Storage)
|
||||
```xml
|
||||
<LibraryMonitorDelay>45</LibraryMonitorDelay>
|
||||
<LibraryUpdateDuration>30</LibraryUpdateDuration>
|
||||
```
|
||||
|
||||
### NAS-Based Setup
|
||||
```xml
|
||||
<LibraryMonitorDelay>120</LibraryMonitorDelay>
|
||||
<LibraryUpdateDuration>30</LibraryUpdateDuration>
|
||||
```
|
||||
|
||||
### Cloud/Remote Storage
|
||||
```xml
|
||||
<LibraryMonitorDelay>300</LibraryMonitorDelay>
|
||||
<LibraryUpdateDuration>60</LibraryUpdateDuration>
|
||||
```
|
||||
|
||||
### Fast SSD, Small Files
|
||||
```xml
|
||||
<LibraryMonitorDelay>30</LibraryMonitorDelay>
|
||||
<LibraryUpdateDuration>15</LibraryUpdateDuration>
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
- [Library Monitoring Documentation](library-monitoring.md)
|
||||
- [File System Watcher Details](file-system-watcher.md)
|
||||
- [Performance Tuning Guide](performance-tuning.md)
|
||||
|
||||
---
|
||||
|
||||
**Last Updated:** 2026-03-03
|
||||
**Minimum Value:** 30 seconds (enforced by code)
|
||||
**Default Value:** 60 seconds
|
||||
**Configurable:** Yes
|
||||
Reference in New Issue
Block a user