From 7e2c08499b1b09b941a4c93817eb4a91e99ee6e7 Mon Sep 17 00:00:00 2001
From: Wendell Jones <wpjonesnh@gmail.com>
Date: Sat, 7 Mar 2026 13:08:28 -0500
Subject: [PATCH] Document automatic empty database initialization feature

---
 sql/README-DATABASE-SETUP.md | 88 ++++++++++++++++++++++++++----------
 1 file changed, 63 insertions(+), 25 deletions(-)

diff --git a/sql/README-DATABASE-SETUP.md b/sql/README-DATABASE-SETUP.md
index 447717da..9a0f5ccd 100644
--- a/sql/README-DATABASE-SETUP.md
+++ b/sql/README-DATABASE-SETUP.md
@@ -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
 
 ---