pgsql-jellyfin/sql/README-DATABASE-SETUP.md

Jellyfin PostgreSQL Database Setup (.NET 11 Preview)

Overview

Due to .NET 11 being a preview release, EF Core migrations cannot run automatically at startup. Database schema must be created manually using SQL scripts.

---

🚀 Initial Database Setup

Step 1: Create Database and Schema

Run the main schema creation script:

psql -U jellyfin -d postgres -f sql/schema_init/create_database_schema.sql

This creates:

• All database schemas (library, activitylog, authentication, etc.)
• All tables with proper columns and data types
• Primary keys and foreign keys
• Base indexes

---

Step 2: Apply Supplementary Performance Indexes

After the main schema is created, apply the performance indexes:

psql -U jellyfin -d jellyfin -f sql/apply-supplementary-indexes-migration.sql

This creates 5 additional performance indexes for:

• Library browsing
• Folder hierarchy
• Recently added content
• Genre/tag filtering
• Episode deduplication

---

Step 3: Apply ActivityLog Index Fix

If the ActivityLogs table exists, apply the final index:

psql -U jellyfin -d jellyfin -f sql/fix-activitylog-index.sql

This creates the 6th performance index for user activity queries.

---

📋 What Changed for .NET 11 Preview

In Code (PostgresDatabaseProvider.cs)

The automatic migration code has been commented out:

// DISABLED: EF Core migrations don't work with .NET 11 preview
// Use manual SQL scripts in Jellyfin.Server/sql/schema_init/ directory instead
logger.LogWarning("EF Core migrations are disabled for .NET 11 preview...");

/* COMMENTED OUT - EF migrations not compatible with .NET 11 preview
await context.Database.MigrateAsync(cancellationToken).ConfigureAwait(false);
*/

On Startup

When Jellyfin starts, it will:

1. ✅ Check database connection
2. ✅ Verify database exists
3. ⚠️ Log warning about pending migrations (not automatically apply them)
4. ✅ Continue with normal startup

You will see this warning in logs:

[WRN] EF Core migrations are disabled for .NET 11 preview. Please apply migrations manually using SQL scripts in sql/schema_init/ directory.

---

🔄 Upgrading Existing Database

If you already have a Jellyfin database and are upgrading:

Option 1: Apply Only Missing Indexes (Recommended)

If your database structure is already correct, just add the performance indexes:

# Apply supplementary indexes
psql -U jellyfin -d jellyfin -f sql/apply-supplementary-indexes-migration.sql

# Apply ActivityLog index fix
psql -U jellyfin -d jellyfin -f sql/fix-activitylog-index.sql

Option 2: Full Schema Recreation (Data Loss!)

⚠️ WARNING: This will delete all data!

Only do this for a fresh start:

# Drop existing database
psql -U jellyfin -d postgres -c "DROP DATABASE IF EXISTS jellyfin;"

# Recreate from schema
psql -U jellyfin -d postgres -f sql/schema_init/create_database_schema.sql
psql -U jellyfin -d jellyfin -f sql/apply-supplementary-indexes-migration.sql
psql -U jellyfin -d jellyfin -f sql/fix-activitylog-index.sql

---

📁 SQL Script Locations

D:\Projects\pgsql-jellyfin\
├── sql/
│   ├── schema_init/
│   │   ├── create_database_schema.sql          ← Main database schema
│   │   └── 10_create_supplementary_indexes.sql ← (EF migration file)
│   ├── apply-supplementary-indexes-migration.sql ← Performance indexes
│   └── fix-activitylog-index.sql                 ← ActivityLog index fix

---

✅ Verification

After running the scripts, verify everything is set up correctly:

-- Check schemas exist
SELECT schema_name FROM information_schema.schemata 
WHERE schema_name IN ('library', 'activitylog', 'authentication', 'displaypreferences');

-- Check migration history
SELECT * FROM library."__EFMigrationsHistory" ORDER BY "MigrationId";

-- Check indexes
SELECT schemaname, tablename, indexname 
FROM pg_indexes 
WHERE indexname LIKE 'idx_%'
ORDER BY tablename, indexname;

Expected:

• ✅ 4+ schemas
• ✅ 3+ migrations in history
• ✅ 6+ custom performance indexes

---

🎯 When .NET 11 Goes GA

When .NET 11 is officially released (no longer preview):

1. Uncomment the migration code in PostgresDatabaseProvider.cs
2. Remove the warning log statements
3. EF Core migrations will work automatically again

---

📞 Need Help?

If you encounter issues:

1. Check logs: Look for database connection errors
2. Verify credentials: Ensure PostgreSQL user has proper permissions
3. Check schema: Run verification queries above
4. Manual fixes: All scripts use IF NOT EXISTS - safe to re-run

---

Created: 2026-03-07
Commit: 0911146 - EF migrations disabled for .NET 11 preview