pgsql-jellyfin/QUICK_REFERENCE.md

Quick Reference: Auto-Migration & Index Checker

✅ YES - Migrations Run Automatically!

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

// 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)

// 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:

psql -U jellyfin -d jellyfin_testsdata -c "SELECT * FROM __EFMigrationsHistory WHERE MigrationId LIKE '%AddSupplementary%';"

Check if indexes exist:

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:

# 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:

dotnet ef database update --project src\Jellyfin.Database\Jellyfin.Database.Providers.Postgres\Jellyfin.Database.Providers.Postgres.csproj

Run SQL script directly:

psql -U jellyfin -d jellyfin_testsdata -f sql\schema_init\10_create_supplementary_indexes.sql

Drop indexes (for testing):

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. 🎉