184 lines
4.7 KiB
Markdown
184 lines
4.7 KiB
Markdown
# 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
|