wjones
78c8d4256c
- Moved all documentation to docs/ and updated README with categorized links and new docs/INDEX.md - Added HOW_TO_SWITCH_DATABASE.md and several new analysis/action docs - Introduced db-config.ps1 for centralized DB config; all scripts now use it for easy DB switching - Added db-quick.ps1 for interactive diagnostics and index management - Updated Add-All-Indexes.bat to use db-config.ps1 - Added Fix-ItemValues-Performance.ps1 to create 3 critical indexes on ItemValues, addressing 1.3B row seq scan issue - Updated performance_indexes.sql with new ItemValues indexes and ANALYZE - Updated diagnostics.sql and database_report.txt for improved output and clarity - All scripts and docs now reference the new config and index optimization workflow
208 lines
5.2 KiB
Markdown
208 lines
5.2 KiB
Markdown
# ⚡ Quick Action Plan - Based on Your Diagnostics
|
|
|
|
## 🎯 What Your Diagnostics Revealed
|
|
|
|
### ✅ Good:
|
|
- No errors, no locks, no blocking
|
|
- Most tables have excellent index usage (94-99%)
|
|
- Supplementary indexes installed correctly
|
|
|
|
### ⚠️ Issues:
|
|
- **ItemValues table**: 1.3 BILLION rows read via sequential scans! 😱
|
|
- **Peoples table**: 918 million rows read
|
|
- **Supplementary indexes**: Almost unused (0-10 uses)
|
|
|
|
---
|
|
|
|
## 🚀 What To Do Now
|
|
|
|
### Step 1: Use Jellyfin Normally (This Week) ⭐
|
|
|
|
The supplementary indexes we created target specific user interactions. **You need to actually use Jellyfin** to see if they help!
|
|
|
|
**Do these actions:**
|
|
|
|
#### Browse Recently Added
|
|
```
|
|
Dashboard → Recently Added
|
|
```
|
|
Tests: `idx_baseitems_datecreated_filtered`
|
|
|
|
#### Filter by Genre/Tags
|
|
```
|
|
Movies → Filter → Genre → Action
|
|
TV Shows → Filter → Tags → Drama
|
|
```
|
|
Tests: `idx_itemvaluesmap_itemvalueid_itemid`
|
|
|
|
#### Browse Libraries
|
|
```
|
|
Movies → Browse folders
|
|
TV Shows → Navigate seasons
|
|
```
|
|
Tests: `idx_baseitems_type_isvirtualitem_topparentid`
|
|
|
|
### Step 2: Run Diagnostics Again (End of Week)
|
|
|
|
```powershell
|
|
& "C:\Program Files\PostgreSQL\18\bin\psql.exe" -U jellyfin -d jellyfin -f sql\diagnostics.sql > diagnostics_week1.txt
|
|
```
|
|
|
|
Compare to today's results:
|
|
- Are supplementary indexes being used more?
|
|
- Has ItemValues improved?
|
|
|
|
### Step 3: Optimize ItemValues Table (Next Week)
|
|
|
|
After we see actual usage patterns, create targeted indexes for ItemValues.
|
|
|
|
---
|
|
|
|
## 📊 Why Supplementary Indexes Show 0 Uses
|
|
|
|
**Your diagnostics show:**
|
|
- 0 active database connections
|
|
- 0 long-running queries
|
|
- Index usage from past activity only
|
|
|
|
**This means:**
|
|
- Database has been idle
|
|
- Indexes only get used when queries run
|
|
- Need to use Jellyfin to generate workload
|
|
|
|
**It's like installing a highway but nobody's driven on it yet!** 🛣️
|
|
|
|
---
|
|
|
|
## 🔧 I Already Fixed One Thing
|
|
|
|
✅ **Updated Statistics** - Ran `ANALYZE` so PostgreSQL knows about the new indexes
|
|
|
|
---
|
|
|
|
## 📅 1-Week Testing Plan
|
|
|
|
| Day | Action | Expected Result |
|
|
|-----|--------|-----------------|
|
|
| **Day 1-2** | Use Jellyfin normally<br>- Browse libraries<br>- Filter by genre<br>- View Recently Added | Generate query workload |
|
|
| **Day 3** | Run diagnostics<br>`sql\diagnostics.sql` | See if indexes are used |
|
|
| **Day 4-7** | Continue using Jellyfin | Build more usage data |
|
|
| **Day 7** | Run diagnostics again<br>Compare to today | Decide which indexes to keep |
|
|
|
|
---
|
|
|
|
## 🎯 Success Metrics
|
|
|
|
After 1 week, you should see:
|
|
|
|
### If Indexes Are Working:
|
|
- `idx_baseitems_datecreated_filtered`: **100+ uses**
|
|
- `idx_itemvaluesmap_itemvalueid_itemid`: **50+ uses**
|
|
- ItemValues seq scans: **Reduced** from 226k
|
|
|
|
### If Indexes Aren't Helping:
|
|
- Still 0-10 uses after heavy use
|
|
- **Action**: Remove unused indexes to save space
|
|
- Create different indexes based on actual query patterns
|
|
|
|
---
|
|
|
|
## 🔥 The Real Problem: ItemValues Table
|
|
|
|
Your diagnostics show the biggest issue isn't what we optimized:
|
|
|
|
**ItemValues Table:**
|
|
- 226,121 sequential scans
|
|
- 1.3 BILLION rows read
|
|
- Only 52% index usage
|
|
- This is killing performance! 😱
|
|
|
|
**Why Our Indexes Didn't Help:**
|
|
We created indexes for:
|
|
- BaseItems (recently added, virtual items, folders)
|
|
- ItemValuesMap (genre/tag mapping)
|
|
- ActivityLogs (user activity)
|
|
|
|
But **NOT** for ItemValues itself!
|
|
|
|
**Next Step:**
|
|
After seeing usage patterns, we'll create indexes specifically for ItemValues table.
|
|
|
|
---
|
|
|
|
## 🎓 What This Teaches Us
|
|
|
|
### Index Creation Is Iterative:
|
|
|
|
1. **Phase 1**: Create indexes based on schema analysis ✅ (Done)
|
|
2. **Phase 2**: Test with real workload ← **You are here**
|
|
3. **Phase 3**: Monitor what's used, remove what's not
|
|
4. **Phase 4**: Create indexes for actual bottlenecks
|
|
5. **Phase 5**: Repeat
|
|
|
|
**You can't optimize until you have real data!**
|
|
|
|
---
|
|
|
|
## ⚠️ Don't Panic About Low Usage
|
|
|
|
**It's normal!** Here's why:
|
|
|
|
1. **Database was idle** - 0 connections when you ran diagnostics
|
|
2. **New indexes** - Just created, haven't had time to prove themselves
|
|
3. **Need workload** - Indexes only matter when queries run
|
|
|
|
**Analogy**: You installed a fire extinguisher. The fact it hasn't been used yet doesn't mean it's useless! 🧯
|
|
|
|
---
|
|
|
|
## 🚦 Quick Status Check
|
|
|
|
### ✅ Done:
|
|
- Supplementary indexes created
|
|
- Statistics updated
|
|
- Diagnostics analyzed
|
|
|
|
### 📋 To Do:
|
|
1. Use Jellyfin normally this week
|
|
2. Run diagnostics end of week
|
|
3. Compare results
|
|
4. Optimize ItemValues table
|
|
5. Remove unused indexes after 30 days
|
|
|
|
---
|
|
|
|
## 💡 Pro Tip: Keep a Log
|
|
|
|
Create a simple log of your Jellyfin usage:
|
|
|
|
```
|
|
Day 1:
|
|
- Browsed Movies library (5 min)
|
|
- Filtered by Action genre (10 items viewed)
|
|
- Viewed Recently Added (scrolled through 20 items)
|
|
|
|
Day 2:
|
|
- Searched for actor "Tom Hanks" (15 results)
|
|
- Watched a movie
|
|
- Browsed TV Shows (10 min)
|
|
```
|
|
|
|
This helps correlate index usage with your actions!
|
|
|
|
---
|
|
|
|
## 🎉 Bottom Line
|
|
|
|
**Your database is healthy!** The issues are optimization opportunities, not critical errors.
|
|
|
|
**Action Items:**
|
|
1. ✅ Statistics updated (done by me)
|
|
2. **Use Jellyfin normally for 1 week** (your task)
|
|
3. **Run diagnostics next week** (we'll do together)
|
|
4. **Optimize based on real data** (next phase)
|
|
|
|
**Keep calm and keep testing!** 🚀
|
|
|
|
See `DATABASE_ANALYSIS_REPORT.md` for the complete technical analysis.
|