Add database setup documentation for .NET 11 preview manual migration workflow

2026-03-07 12:52:52 -05:00
parent 091114657b
commit 5c711bc235
1 changed files with 183 additions and 0 deletions
@@ -0,0 +1,183 @@
+# 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:
+
+```sh
+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:
+
+```sh
+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:
+
+```sh
+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**:
+
+```csharp
+// 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:
+
+```sh
+# 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:
+
+```sh
+# 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:
+
+```sql
+-- 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