Document automatic empty database initialization feature

2026-03-07 13:08:28 -05:00
parent 75acefe989
commit 7e2c08499b
1 changed files with 63 additions and 25 deletions
@@ -2,11 +2,52 @@

 ## 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.
+Due to .NET 11 being a preview release, EF Core migrations cannot run automatically at startup. Database schema is created using SQL scripts.
+
+**✨ NEW: Automatic Schema Initialization**  
+If the database is **empty** (no `library` schema found), Jellyfin will **automatically execute** `sql/schema_init/create_database_schema.sql` at startup!

 ---

-## 🚀 Initial Database Setup
+## 🚀 Automatic Setup (Recommended)
+
+### For Fresh Database - Zero Configuration!
+
+1. **Create an empty PostgreSQL database**:
+   ```sh
+   psql -U postgres -c "CREATE DATABASE jellyfin OWNER jellyfin;"
+   ```
+
+2. **Just start Jellyfin**:
+   ```sh
+   dotnet run --project Jellyfin.Server
+   ```
+
+**That's it!** Jellyfin will:
+- ✅ Detect the database is empty (no `library` schema)
+- ✅ Automatically load `sql/schema_init/create_database_schema.sql`
+- ✅ Execute the full schema creation script
+- ✅ Initialize all tables, schemas, and base indexes
+- ✅ Continue with normal startup
+
+**What you'll see in logs**:
+```
+[INF] Database is empty (library schema not found). Attempting to initialize from SQL script...
+[INF] Found schema script at: D:\Jellyfin\sql\schema_init\create_database_schema.sql
+[INF] Executing create_database_schema.sql to initialize database...
+[INF] Successfully initialized database from SQL script
+[INF] Database schema verification complete.
+```
+
+---
+
+## 🔧 Manual Setup (Alternative)
+
+If you prefer manual control or the automatic setup fails:
+
+## 🔧 Manual Setup (Alternative)
+
+If you prefer manual control or the automatic setup fails:

 ### Step 1: Create Database and Schema

@@ -55,32 +96,29 @@ This creates the 6th performance index for user activity queries.

 ## 📋 What Changed for .NET 11 Preview

+### Automatic SQL Script Execution ✨
+
+**New Feature**: Empty database auto-initialization!
+
+When Jellyfin starts:
+1. ✅ Connects to PostgreSQL database
+2. ✅ Checks if `library` schema exists
+3. ✅ **If empty**: Automatically runs `sql/schema_init/create_database_schema.sql`
+4. ✅ **If not empty**: Skips initialization and proceeds normally
+5. ⚠️ Logs warning about any pending migrations (doesn't apply them)
+6. ✅ Continues with normal startup
+
 ### In Code (`PostgresDatabaseProvider.cs`)

-The automatic migration code has been **commented out**:
+**Disabled**:
+- ❌ `context.Database.EnsureCreatedAsync()` - Bypasses migration tracking
+- ❌ `context.Database.MigrateAsync()` - Not compatible with .NET 11 preview

-```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.
-```
+**Added**:
+- ✅ Empty database detection (checks for `library` schema)
+- ✅ Automatic SQL script execution from `sql/schema_init/create_database_schema.sql`
+- ✅ Proper error handling and logging
+- ✅ 10-minute timeout for large schema creation

 ---