pgsql-jellyfin/docs/QUICK_REFERENCE.md

# Quick Reference: Auto-Migration & Index Checker

## ✅ YES - Migrations Run Automatically!

**Found in**: `Jellyfin.Server\Program.cs` → `PostgresDatabaseProvider.EnsureTablesExistAsync()`

```csharp
// Line 205 in Program.cs
await databaseProvider.EnsureTablesExistAsync().ConfigureAwait(false);

// In PostgresDatabaseProvider.cs (line 379)
await context.Database.MigrateAsync(cancellationToken).ConfigureAwait(false);
```

### This means:
- ✅ New database? Migrations apply automatically
- ✅ Pending migrations? Applied on startup
- ✅ Your 5 supplementary indexes? Created automatically via `20260227000000_AddSupplementaryIndexes` migration

---

## ✅ Index Checker Added to Startup

**Location**: `PostgresDatabaseProvider.EnsureTablesExistAsync()` (line 457)

```csharp
// After migrations are applied and tables verified:
await CheckSupplementaryIndexesAsync(connection, cancellationToken).ConfigureAwait(false);
```

### What it checks:
1. `idx_baseitems_type_isvirtualitem_topparentid` - Filtered library browsing
2. `idx_baseitems_topparentid_isfolder` - Folder hierarchy
3. `idx_baseitems_datecreated_filtered` - Recently added view
4. `idx_itemvaluesmap_itemvalueid_itemid` - Genre/tag lookup
5. `idx_activitylogs_userid_datecreated` - User activity

### What it does:
- ✅ Counts how many exist (0-5)
- ⚠️ Logs warning if any missing
- ℹ️ Provides command to fix
- ✅ Non-blocking (startup continues)

---

## Expected Startup Flow

### Scenario 1: New Database (Empty)
```
[INFO] Checking PostgreSQL database for missing tables...
[INFO] Found 0 applied migrations
[INFO] Found 2 pending migrations: 20260226165957_InitialCreate, 20260227000000_AddSupplementaryIndexes
[INFO] Applying migrations...
[INFO] Successfully applied 2 migrations
[INFO] Database table verification complete
[INFO] All 5 supplementary performance indexes are present. ✅
```

### Scenario 2: Existing Database (No Supplementary Indexes)
```
[INFO] Checking PostgreSQL database for missing tables...
[INFO] Found 1 pending migrations: 20260227000000_AddSupplementaryIndexes
[INFO] Applying migrations...
[INFO] Successfully applied 1 migrations
[INFO] Database table verification complete
[INFO] All 5 supplementary performance indexes are present. ✅
```

### Scenario 3: Existing Database (Already Has Indexes)
```
[INFO] Checking PostgreSQL database for missing tables...
[INFO] All database tables are up to date. No migrations needed.
[INFO] Database table verification complete
[INFO] All 5 supplementary performance indexes are present. ✅
```

### Scenario 4: Indexes Manually Deleted (Warning)
```
[INFO] All database tables are up to date. No migrations needed.
[INFO] Database table verification complete
[WARN] Found 3/5 supplementary performance indexes. Missing: idx_baseitems_datecreated_filtered, idx_itemvaluesmap_itemvalueid_itemid ⚠️
[WARN] Run migration '20260227000000_AddSupplementaryIndexes' or execute 'sql/schema_init/10_create_supplementary_indexes.sql' to add missing indexes for better performance.
```

---

## How to Verify

### Check if migration exists:
```powershell
psql -U jellyfin -d jellyfin_testsdata -c "SELECT * FROM __EFMigrationsHistory WHERE MigrationId LIKE '%AddSupplementary%';"
```

### Check if indexes exist:
```powershell
psql -U jellyfin -d jellyfin_testsdata -c "
SELECT indexname, tablename, schemaname
FROM pg_indexes
WHERE indexname IN (
    'idx_baseitems_type_isvirtualitem_topparentid',
    'idx_baseitems_topparentid_isfolder',
    'idx_baseitems_datecreated_filtered',
    'idx_itemvaluesmap_itemvalueid_itemid',
    'idx_activitylogs_userid_datecreated'
)
ORDER BY indexname;
"
```

### Check Jellyfin startup logs:
```powershell
# Windows
Get-Content "C:\ProgramData\Jellyfin\log\log_*.txt" | Select-String "supplementary"

# Linux
grep "supplementary" /var/log/jellyfin/*.log
```

---

## Manual Operations (If Needed)

### Apply migration manually:
```powershell
dotnet ef database update --project src\Jellyfin.Database\Jellyfin.Database.Providers.Postgres\Jellyfin.Database.Providers.Postgres.csproj
```

### Run SQL script directly:
```powershell
psql -U jellyfin -d jellyfin_testsdata -f sql\schema_init\10_create_supplementary_indexes.sql
```

### Drop indexes (for testing):
```sql
DROP INDEX CONCURRENTLY IF EXISTS library.idx_baseitems_type_isvirtualitem_topparentid;
DROP INDEX CONCURRENTLY IF EXISTS library.idx_baseitems_topparentid_isfolder;
DROP INDEX CONCURRENTLY IF EXISTS library.idx_baseitems_datecreated_filtered;
DROP INDEX CONCURRENTLY IF EXISTS library.idx_itemvaluesmap_itemvalueid_itemid;
DROP INDEX CONCURRENTLY IF EXISTS activitylog.idx_activitylogs_userid_datecreated;
```

---

## Summary

✅ **Migrations**: Auto-run on startup  
✅ **Index Checker**: Integrated and running  
✅ **Build**: Successful  
✅ **Indexes**: Will be created automatically  

**You're all set!** Just start Jellyfin and the indexes will be created automatically. 🎉