4b7eca8a46
All checks were successful
Reindex Knowledge Base / reindex (push) Successful in 3s
Adds title, description, type, domain, and tags frontmatter to every doc for improved KB semantic search. The description field is prepended to every search chunk, and domain/type/tags enable filtered queries. Type values: context, guide, runbook, reference, troubleshooting Domain values match directory structure (networking, docker, etc.) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
100 lines
2.5 KiB
Markdown
100 lines
2.5 KiB
Markdown
---
|
|
title: "Network Filesystem Limitations"
|
|
description: "SQLite WAL locking failures on NFS/CIFS/sshfs, hybrid storage patterns for databases vs media, and mount optimization for network filesystems."
|
|
type: reference
|
|
domain: networking
|
|
tags: [nfs, cifs, sqlite, filesystem, storage, performance]
|
|
---
|
|
|
|
# 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
|
|
``` |