pgsql-jellyfin/DATABASE_CONFIGURATION_GUIDE.md

Database Configuration Guide

Overview

Jellyfin's database configuration is stored in the database.xml file located in your configuration directory. This file is automatically created on first startup with SQLite as the default database provider.

As of this update, the configuration file includes preset configurations for both SQLite and PostgreSQL, making it easy to switch between database providers without having to remember all the configuration options.

Configuration File Location

The database.xml file is located in your Jellyfin configuration directory:

• Linux: /etc/jellyfin/database.xml or ~/.config/jellyfin/database.xml
• Windows: %ProgramData%\Jellyfin\config\database.xml
• Docker: Typically /config/database.xml in your config volume

Quick Start: Switching Between Databases

Method 1: Edit database.xml (Recommended)

1. Stop Jellyfin

   # Linux
   sudo systemctl stop jellyfin
   
   # Windows
   net stop JellyfinServer
   
   # Docker
   docker stop jellyfin
   

2. Edit database.xml

   Change this line:

   <DatabaseType>Jellyfin-SQLite</DatabaseType>
   

   To:

   <DatabaseType>Jellyfin-PostgreSQL</DatabaseType>
   

3. Add PostgreSQL connection settings (uncomment and configure):

   <CustomProviderOptions>
     <PluginName>Jellyfin.Database.Providers.Postgres</PluginName>
     <PluginAssembly>Jellyfin.Database.Providers.Postgres.dll</PluginAssembly>
     <ConnectionString></ConnectionString>
     <Options>
       <CustomDatabaseOption>
         <Key>host</Key>
         <Value>localhost</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_secure_password</Value>
       </CustomDatabaseOption>
     </Options>
   </CustomProviderOptions>
   

4. Start Jellyfin

   sudo systemctl start jellyfin
   

Method 2: Use Preset Configurations

The database.xml file now includes preset configurations that serve as templates. These presets show you exactly what settings are needed for each database type.

Available Presets:

• SQLite - Default single-file database
• PostgreSQL-Local - PostgreSQL on localhost

To use a preset:

1. Look at the preset configuration in the <PresetConfigurations> section
2. Copy the settings to the active configuration at the top of the file
3. Configure any additional options (like PostgreSQL credentials)

Configuration File Structure

<?xml version="1.0" encoding="utf-8"?>
<DatabaseConfigurationOptions>
  
  <!-- ACTIVE CONFIGURATION -->
  <DatabaseType>Jellyfin-SQLite</DatabaseType>
  <LockingBehavior>NoLock</LockingBehavior>
  
  <!-- POSTGRESQL OPTIONS (when using PostgreSQL) -->
  <CustomProviderOptions>
    <!-- PostgreSQL connection settings -->
  </CustomProviderOptions>
  
  <!-- BACKUP SETTINGS -->
  <BackupOptions>
    <EnableAutoBackup>false</EnableAutoBackup>
    <BackupRetentionDays>30</BackupRetentionDays>
  </BackupOptions>
  
  <!-- PRESET CONFIGURATIONS (Templates) -->
  <PresetConfigurations>
    <!-- SQLite and PostgreSQL presets -->
  </PresetConfigurations>
  
</DatabaseConfigurationOptions>

Configuration Properties

DatabaseType

The active database provider to use.

Options:

• Jellyfin-SQLite - Use SQLite database (default)
• Jellyfin-PostgreSQL - Use PostgreSQL database

Example:

<DatabaseType>Jellyfin-PostgreSQL</DatabaseType>

LockingBehavior

How Jellyfin should handle database locking.

Options:

• NoLock - No locking (recommended for most installations)
• Pessimistic - Lock rows before reading
• Optimistic - Check for conflicts after reading

Default: NoLock

Example:

<LockingBehavior>NoLock</LockingBehavior>

CustomProviderOptions

Connection settings for PostgreSQL (not needed for SQLite).

Required Properties:

• PluginName - Always set to Jellyfin.Database.Providers.Postgres
• PluginAssembly - Always set to Jellyfin.Database.Providers.Postgres.dll
• ConnectionString - Leave empty (connection built from Options)
• Options - List of key-value pairs for connection settings

PostgreSQL Options:

Key	Description	Default	Example
host	PostgreSQL server hostname	localhost	localhost, 192.168.1.100, db.example.com
port	PostgreSQL server port	5432	5432
database	Database name	jellyfin	jellyfin, jellyfin_prod
username	Database username	jellyfin	jellyfin, postgres
password	Database password	(empty)	your_secure_password
connection-timeout	Connection timeout in seconds	15	15, 30

Example:

<CustomProviderOptions>
  <PluginName>Jellyfin.Database.Providers.Postgres</PluginName>
  <PluginAssembly>Jellyfin.Database.Providers.Postgres.dll</PluginAssembly>
  <ConnectionString></ConnectionString>
  <Options>
    <CustomDatabaseOption>
      <Key>host</Key>
      <Value>localhost</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>MySecurePassword123</Value>
    </CustomDatabaseOption>
  </Options>
</CustomProviderOptions>

BackupOptions

Configure automatic database backups (optional).

Properties:

• EnableAutoBackup - Enable/disable automatic backups
• BackupRetentionDays - How many days to keep backups

Example:

<BackupOptions>
  <EnableAutoBackup>true</EnableAutoBackup>
  <BackupRetentionDays>30</BackupRetentionDays>
</BackupOptions>

PresetConfigurations

Template configurations for quick reference. These are NOT active configurations - they're just examples stored in the file for your convenience.

Complete Examples

Example 1: SQLite Configuration

<?xml version="1.0" encoding="utf-8"?>
<DatabaseConfigurationOptions>
  <DatabaseType>Jellyfin-SQLite</DatabaseType>
  <LockingBehavior>NoLock</LockingBehavior>
  
  <BackupOptions>
    <EnableAutoBackup>false</EnableAutoBackup>
    <BackupRetentionDays>30</BackupRetentionDays>
  </BackupOptions>
  
  <PresetConfigurations>
    <!-- Presets stored here for reference -->
  </PresetConfigurations>
</DatabaseConfigurationOptions>

Example 2: PostgreSQL Configuration (Localhost)

<?xml version="1.0" encoding="utf-8"?>
<DatabaseConfigurationOptions>
  <DatabaseType>Jellyfin-PostgreSQL</DatabaseType>
  <LockingBehavior>NoLock</LockingBehavior>
  
  <CustomProviderOptions>
    <PluginName>Jellyfin.Database.Providers.Postgres</PluginName>
    <PluginAssembly>Jellyfin.Database.Providers.Postgres.dll</PluginAssembly>
    <ConnectionString></ConnectionString>
    <Options>
      <CustomDatabaseOption>
        <Key>host</Key>
        <Value>localhost</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>YourSecurePassword</Value>
      </CustomDatabaseOption>
    </Options>
  </CustomProviderOptions>
  
  <BackupOptions>
    <EnableAutoBackup>true</EnableAutoBackup>
    <BackupRetentionDays>30</BackupRetentionDays>
  </BackupOptions>
</DatabaseConfigurationOptions>

Example 3: PostgreSQL Configuration (Remote Server)

<?xml version="1.0" encoding="utf-8"?>
<DatabaseConfigurationOptions>
  <DatabaseType>Jellyfin-PostgreSQL</DatabaseType>
  <LockingBehavior>NoLock</LockingBehavior>
  
  <CustomProviderOptions>
    <PluginName>Jellyfin.Database.Providers.Postgres</PluginName>
    <PluginAssembly>Jellyfin.Database.Providers.Postgres.dll</PluginAssembly>
    <ConnectionString></ConnectionString>
    <Options>
      <CustomDatabaseOption>
        <Key>host</Key>
        <Value>db.example.com</Value>
      </CustomDatabaseOption>
      <CustomDatabaseOption>
        <Key>port</Key>
        <Value>5432</Value>
      </CustomDatabaseOption>
      <CustomDatabaseOption>
        <Key>database</Key>
        <Value>jellyfin_production</Value>
      </CustomDatabaseOption>
      <CustomDatabaseOption>
        <Key>username</Key>
        <Value>jellyfin_user</Value>
      </CustomDatabaseOption>
      <CustomDatabaseOption>
        <Key>password</Key>
        <Value>VerySecurePassword123!</Value>
      </CustomDatabaseOption>
      <CustomDatabaseOption>
        <Key>connection-timeout</Key>
        <Value>30</Value>
      </CustomDatabaseOption>
    </Options>
  </CustomProviderOptions>
  
  <BackupOptions>
    <EnableAutoBackup>true</EnableAutoBackup>
    <BackupRetentionDays>7</BackupRetentionDays>
  </BackupOptions>
</DatabaseConfigurationOptions>

Migration Between Databases

From SQLite to PostgreSQL

1. Backup your current SQLite database

   cp jellyfin.db jellyfin.db.backup
   

2. Set up PostgreSQL server and create database

   CREATE DATABASE jellyfin;
   CREATE USER jellyfin WITH PASSWORD 'your_password';
   GRANT ALL PRIVILEGES ON DATABASE jellyfin TO jellyfin;
   

3. Stop Jellyfin

4. Edit database.xml to use PostgreSQL (see examples above)

5. Start Jellyfin - Migrations will run automatically

6. Note: This creates a fresh database. To migrate data, you'll need to use Jellyfin's backup/restore features or export/import your library.

From PostgreSQL to SQLite

1. Stop Jellyfin

2. Edit database.xml - Change DatabaseType to Jellyfin-SQLite and remove CustomProviderOptions

3. Start Jellyfin - A new SQLite database will be created

4. Note: Data migration requires backup/restore or manual export/import

Troubleshooting

Configuration not taking effect

Solution: Ensure you've stopped Jellyfin before editing the configuration file, and that the file is saved with proper XML formatting.

PostgreSQL connection fails

Check:

1. PostgreSQL server is running: sudo systemctl status postgresql
2. Database exists: psql -l
3. User has permissions: psql -U jellyfin -d jellyfin
4. Firewall allows connection on port 5432
5. Password is correct in database.xml

Cannot find database.xml

Solution: The file is created on first startup. If missing:

1. Start Jellyfin once to generate it
2. Or copy from database.xml.example in the source repository

Preset configurations not working

Important: Presets are templates only! They don't activate automatically. You must:

1. Copy the DatabaseType from the preset to the active configuration
2. Add CustomProviderOptions if needed for PostgreSQL
3. Configure the actual connection settings

Security Considerations

1. Protect database.xml - It contains passwords

   chmod 600 /etc/jellyfin/database.xml
   chown jellyfin:jellyfin /etc/jellyfin/database.xml
   

2. Use strong PostgreSQL passwords

3. Restrict network access to PostgreSQL server

4. Enable automatic backups for production systems

5. Don't commit database.xml to version control with real passwords

See Also

• FILE_BASED_STARTUP_CONFIG.md - Path configuration
• TROUBLESHOOTING_EF_PENDING_CHANGES.md - Database migration issues
• startup.json.example - Path configuration template
• database.xml.example - Database configuration template