wjones/pgsql-jellyfin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2183ed4d632978d4b885ac33a84f5fb966af6f1c
pgsql-jellyfin/README-POSTGRESQL.md
T

9.5 KiB
Raw Blame History

Jellyfin with PostgreSQL Support

This is a fork of Jellyfin that adds PostgreSQL database support for .NET 11 preview.

Features

  • ✅ PostgreSQL database provider implementation
  • ✅ Automatic database initialization from SQL scripts
  • ✅ Remote database support with connection string configuration
  • ✅ Database backup/restore via pg_dump/pg_restore
  • ✅ Migration system disabled in favor of SQL scripts
  • ✅ Support for both local and remote PostgreSQL servers

Requirements

System Dependencies (Linux)

Jellyfin requires certain system libraries to be installed:

Debian/Ubuntu-based systems:

sudo apt-get update
sudo apt-get install -y \
    libfontconfig1 \
    libfreetype6 \
    libssl3 \
    libicu-dev

RHEL/CentOS/Fedora-based systems:

sudo dnf install -y \
    fontconfig \
    freetype \
    openssl \
    libicu

Arch Linux:

sudo pacman -S fontconfig freetype2 openssl icu

Note: The libfontconfig1 library is required for SkiaSharp (image processing). Without it, Jellyfin will fail to start with:

libfontconfig.so.1: cannot open shared object file: No such file or directory

PostgreSQL Requirements

  • PostgreSQL 12 or higher (tested with PostgreSQL 18.3)
  • psql client tools (for automatic schema initialization)
  • Network access to PostgreSQL server (if using remote database)

Install PostgreSQL client tools:

Debian/Ubuntu:

sudo apt-get install -y postgresql-client

RHEL/CentOS/Fedora:

sudo dnf install -y postgresql

Verify psql is available:

psql --version

Database Configuration

Option 1: Using ConnectionString (Recommended)

Create or edit config/database.xml in your Jellyfin data directory:

<?xml version="1.0" encoding="utf-8"?>
<DatabaseConfigurationOptions>
  <DatabaseType>Jellyfin-PostgreSQL</DatabaseType>
  <LockingBehavior>NoLock</LockingBehavior>
  
  <CustomProviderOptions>
    <PluginName>Jellyfin-PostgreSQL</PluginName>
    <PluginAssembly>Jellyfin.Database.Providers.Postgres</PluginAssembly>
    
    <!-- Connection string with all parameters -->
    <ConnectionString>Host=192.168.1.100;Port=5432;Database=jellyfin;Username=jellyfin;Password=your_password_here</ConnectionString>
  </CustomProviderOptions>
  
  <!-- Optional: Backup configuration (works for both local and remote databases) -->
  <BackupOptions>
    <PgDumpPath>pg_dump</PgDumpPath>
    <PgRestorePath>pg_restore</PgRestorePath>
    <BackupFormat>custom</BackupFormat>
    <IncludeBlobs>true</IncludeBlobs>
    <CompressionLevel>6</CompressionLevel>
    <TimeoutSeconds>1800</TimeoutSeconds>
    <VerboseOutput>true</VerboseOutput>
  </BackupOptions>
</DatabaseConfigurationOptions>

Option 2: Using Individual Options

<?xml version="1.0" encoding="utf-8"?>
<DatabaseConfigurationOptions>
  <DatabaseType>Jellyfin-PostgreSQL</DatabaseType>
  
  <CustomProviderOptions>
    <PluginName>Jellyfin-PostgreSQL</PluginName>
    <PluginAssembly>Jellyfin.Database.Providers.Postgres</PluginAssembly>
    
    <Options>
      <CustomDatabaseOption>
        <Key>Host</Key>
        <Value>192.168.1.100</Value>
      </CustomDatabaseOption>
      
      <CustomDatabaseOption>
        <Key>Port</Key>
        <Value>5432</Value>
      </CustomDatabaseOption>
      
      <CustomDatabaseOption>
        <Key>Database</Key>
        <Value>jellyfin</Value>
      </CustomDatabaseOption>
      
      <CustomDatabaseOption>
        <Key>Username</Key>
        <Value>jellyfin</Value>
      </CustomDatabaseOption>
      
      <CustomDatabaseOption>
        <Key>Password</Key>
        <Value>your_password_here</Value>
      </CustomDatabaseOption>
    </Options>
  </CustomProviderOptions>
</DatabaseConfigurationOptions>

Option 3: Hybrid (ConnectionString + Overrides)

Individual options take precedence over ConnectionString:

<CustomProviderOptions>
  <!-- Base connection -->
  <ConnectionString>Host=192.168.1.100;Port=5432;Database=jellyfin;Username=jellyfin</ConnectionString>
  
  <!-- Override just the password -->
  <Options>
    <CustomDatabaseOption>
      <Key>Password</Key>
      <Value>production_password</Value>
    </CustomDatabaseOption>
  </Options>
</CustomProviderOptions>

Database Initialization

Automatic Initialization

When Jellyfin starts with an empty database:

  1. Database Check: Checks if the database exists (creates if missing)
  2. Table Check: Checks if users.Users table exists
  3. Auto-Initialize: If tables don't exist, automatically runs sql/schema_init/create_database_schema.sql via psql
  4. Schema Verification: Verifies all required schemas and tables are present

Requirements for automatic initialization:

  • ✅ psql command must be in system PATH
  • ✅ Database must exist (created automatically or manually)
  • ✅ SQL script must be deployed: sql/schema_init/create_database_schema.sql

Manual Initialization

If psql is not available or automatic initialization fails:

# Create database first
createdb -U postgres jellyfin

# Run schema creation script
psql -U postgres -d jellyfin -f /path/to/jellyfin/sql/schema_init/create_database_schema.sql

Startup Logs

Successful Startup (Empty Database):

[INF] PostgreSQL connection: Host="192.168.1.100", Port=5432, Database="jellyfin", ...
[INF] Database tables not found (users.Users table missing). Initializing from SQL script...
[INF] Found schema script at: .../sql/schema_init/create_database_schema.sql
[INF] Executing create_database_schema.sql (this may take several minutes)...
[INF] Executing via psql: psql -h 192.168.1.100 -p 5432 -U jellyfin -d jellyfin -f "..."
[INF] ✅ Successfully initialized database from SQL script via psql
[INF] Database is ready. You can now start Jellyfin.
[DBG] Schema 'users' contains 4 tables
[DBG] Schema 'library' contains 45 tables
[DBG] Schema 'activitylog' contains 1 tables
[INF] ✅ Database schema verification complete
[INF] There are 0 migrations for stage CoreInitialisation
[INF] There are 24 migrations for stage AppInitialisation

Successful Startup (Existing Database):

[INF] PostgreSQL connection: Host="192.168.1.100", Port=5432, Database="jellyfin", ...
[INF] Database tables exist (users.Users table found)
[DBG] Schema 'users' contains 4 tables
[DBG] Schema 'library' contains 45 tables
[INF] ✅ Database schema verification complete

Troubleshooting

Error: libfontconfig.so.1: cannot open shared object file

Cause: Missing system dependency

Solution:

# Debian/Ubuntu
sudo apt-get install -y libfontconfig1

# RHEL/Fedora
sudo dnf install -y fontconfig

Error: psql command not found

Cause: PostgreSQL client tools not installed

Solution:

# Debian/Ubuntu
sudo apt-get install -y postgresql-client

# RHEL/Fedora
sudo dnf install -y postgresql

Error: Failed to connect to 127.0.0.1:5432

Cause: Configuration not loading correctly (using default localhost)

Solution:

  • Verify database.xml is in the correct location (/var/lib/jellyfin/config/database.xml on Linux)
  • Check that ConnectionString or individual Options are properly configured
  • Ensure Host is set to your remote server IP/hostname

Error: database "jellyfin" does not exist

Cause: Database wasn't created automatically (rare)

Solution:

# Create database manually
createdb -U postgres -h your-server jellyfin

# Grant privileges
psql -U postgres -h your-server -c "GRANT ALL PRIVILEGES ON DATABASE jellyfin TO jellyfin;"

# Restart Jellyfin (it will create tables automatically)

Architecture

Database Schema

  • activitylog - Activity log entries
  • authentication - API keys, devices, device options
  • displaypreferences - User display preferences
  • library - Media library data (BaseItems, metadata, etc.)
  • users - User accounts, permissions, preferences

Migration System

Entity Framework migrations are DISABLED for .NET 11 preview. Schema changes are managed via SQL scripts:

  • Core migrations: Disabled (no database structure changes via EF)
  • Application migrations: Enabled (configuration and data migrations only)

Why: EF migrations in preview builds can cause schema inconsistencies. SQL scripts provide reliable schema management.

Backup and Restore

Automatic Backups (via pg_dump)

Configured in database.xml:

<BackupOptions>
  <PgDumpPath>pg_dump</PgDumpPath>
  <BackupFormat>custom</BackupFormat>
  <CompressionLevel>6</CompressionLevel>
</BackupOptions>

Works for both local and remote databases!

Manual Backup

# Backup to custom format (compressed)
pg_dump -h your-server -U jellyfin -d jellyfin -Fc -f jellyfin_backup.dump

# Backup to SQL format
pg_dump -h your-server -U jellyfin -d jellyfin -f jellyfin_backup.sql

Manual Restore

# Restore from custom format
pg_restore -h your-server -U jellyfin -d jellyfin jellyfin_backup.dump

# Restore from SQL format
psql -h your-server -U jellyfin -d jellyfin -f jellyfin_backup.sql

Building from Source

# Clone repository
git clone https://github.com/yourusername/jellyfin.git
cd jellyfin

# Checkout the upgrade branch
git checkout upgrade-to-NET11

# Build
dotnet build

# Run
cd Jellyfin.Server
dotnet run

Contributing

This is a development/preview branch. For production use, please use the official Jellyfin releases.

License

GNU General Public License v2.0 (same as Jellyfin)

Credits

Based on Jellyfin with PostgreSQL support and .NET 11 compatibility.

Reference in New Issue View Git Blame Copy Permalink