# Network Filesystem Limitations

## SQLite on Network Filesystems

### The Problem
SQLite's WAL (Write-Ahead Logging) mode requires proper file locking that many network filesystems don't support:

```
[ERROR] Tdarr_Server - Error: SQLITE_BUSY: database is locked
[ERROR] Tdarr_Server - {
  "func": "run", 
  "query": "PRAGMA journal_mode = WAL"
}
```

### Affected Filesystems
- ❌ **NFS** - Inconsistent locking behavior
- ❌ **SMB/CIFS** - Limited locking support  
- ❌ **sshfs** - No proper locking
- ✅ **Local ext4/xfs/btrfs** - Full locking support

### Solutions

#### Hybrid Storage Pattern
```yaml
volumes:
  # Database: Local storage
  - ./tdarr/server:/app/server
  
  # Backups: Network storage  
  - /mnt/nas/tdarr/backups:/app/server/Tdarr/Backups
  
  # Media: Network storage (read-mostly)
  - /mnt/nas/media:/media
```

#### Application-Specific Fixes
```yaml
# Force SQLite to use different journal mode
environment:
  - SQLITE_JOURNAL_MODE=DELETE  # Less efficient but compatible
```

## Performance Considerations

### Local vs Network Storage
| Operation | Local SSD | Gigabit NFS | 10Gb NFS |
|-----------|-----------|-------------|----------|
| Database writes | <1ms | 10-50ms | 2-10ms |
| Config reads | <1ms | 5-15ms | 1-5ms |
| Large file reads | 500MB/s | 100MB/s | 800MB/s |

### When to Use Network Storage
- ✅ **Large static files** (media, backups)
- ✅ **Shared access** between multiple services
- ✅ **Centralized backups**
- ❌ **Frequent small writes** (databases, logs)
- ❌ **Applications requiring file locking**

## Troubleshooting

### Symptoms of Network FS Issues
- Database locked errors
- Slow application startup
- Intermittent connection failures
- File corruption on network interruption

### Diagnostic Commands
```bash
# Test file locking
flock /mnt/nas/test.lock -c "sleep 5" &
flock /mnt/nas/test.lock -c "echo success"

# Monitor network filesystem performance
iotop -ao
iostat -x 1

# Check mount options
mount | grep nfs
cat /proc/mounts | grep cifs
```

### Mount Optimization
```bash
# NFS optimizations
mount -t nfs -o rw,hard,intr,rsize=8192,wsize=8192,timeo=14 \
  server:/path /mnt/point

# CIFS optimizations  
mount -t cifs //server/share /mnt/point \
  -o username=user,cache=loose,file_mode=0644,dir_mode=0755
```