pgsql-jellyfin/docs/FEATURE_DATABASE_TABLE_VERIFICATION.md

Database Table Verification and Auto-Creation Feature

Overview

Added automatic database table verification and creation during Jellyfin startup. This ensures all required tables exist and automatically applies any pending Entity Framework Core migrations.

Changes Made

1. Interface Update

File: src/Jellyfin.Database/Jellyfin.Database.Implementations/IJellyfinDatabaseProvider.cs

• Added EnsureTablesExistAsync method to the IJellyfinDatabaseProvider interface
• This method is responsible for checking and creating missing database tables

2. PostgreSQL Provider Implementation

File: src/Jellyfin.Database/Jellyfin.Database.Providers.Postgres/PostgresDatabaseProvider.cs

• Implemented EnsureTablesExistAsync method
• Checks for pending EF Core migrations
• Applies migrations if needed using Database.MigrateAsync()
• Verifies each schema (activitylog, authentication, displaypreferences, library, users) contains tables
• Logs warnings if schemas exist but contain no tables
• Provides detailed logging throughout the process

3. SQLite Provider Implementation

File: src/Jellyfin.Database/Jellyfin.Database.Providers.Sqlite/SqliteDatabaseProvider.cs

• Implemented EnsureTablesExistAsync method for SQLite
• Checks for pending migrations
• Applies migrations if needed
• Verifies database integrity
• Logs table count and completion status

4. Startup Integration

File: Jellyfin.Server/Program.cs

• Added call to EnsureTablesExistAsync in the StartServer method
• Executes after PrepareDatabaseProvider but before backup restoration
• Runs early in the startup process to ensure database is ready

How It Works

1. During Startup: After the database provider is prepared, the system calls EnsureTablesExistAsync()
2. Migration Check: The method checks if there are any pending EF Core migrations
3. Migration Application: If migrations are pending, they are automatically applied
4. Table Verification: The method verifies that all expected schemas contain tables
5. Logging: Detailed logs are provided for each step:
   • Number of pending migrations found
   • Migration application progress
   • Schema verification results
   • Warnings for empty schemas

Benefits

• Automatic Recovery: Automatically fixes missing tables by applying migrations
• Early Detection: Catches database schema issues during startup before they cause runtime errors
• Detailed Logging: Provides clear visibility into what's happening with the database
• Prevention: Prevents errors like "relation does not exist" by ensuring all tables are created
• Both Databases: Works for both PostgreSQL and SQLite providers

Example Logs

When the system starts and finds missing tables:

[INF] Checking PostgreSQL database for missing tables...
[INF] Found 3 pending migrations. Applying migrations...
[INF] Successfully applied 3 migrations
[DBG] Schema 'activitylog' contains 1 tables
[DBG] Schema 'authentication' contains 3 tables
[DBG] Schema 'displaypreferences' contains 4 tables
[DBG] Schema 'library' contains 15 tables
[DBG] Schema 'users' contains 4 tables
[INF] Database table verification complete

When everything is up to date:

[INF] Checking PostgreSQL database for missing tables...
[INF] All database tables are up to date. No migrations needed.
[INF] Database table verification complete

Testing Recommendations

1. Fresh Database: Test with a completely new database to verify migrations are applied
2. Partial Database: Test with a database missing some tables to ensure they're created
3. Complete Database: Test with an up-to-date database to ensure it skips unnecessary work
4. Schema Verification: Verify that the warning logs appear if schemas exist but are empty

Notes

• The method is called automatically during startup - no configuration needed
• Migrations are applied in the correct order as defined by EF Core
• The process will throw exceptions if migrations fail, preventing startup with a broken database
• Both PostgreSQL and SQLite providers are fully supported