wjones
8f860a8ec3
- All DLLs now output to lib\[Configuration]\[TargetFramework]\ at repo root (see Directory.Build.props) - .gitignore updated to exclude /lib/ - On first run, startup.json is auto-generated with OS-appropriate default paths (Windows, Linux, macOS, or portable) - Removes null/example config; generated config is immediately usable and clearly documented - Extensive new documentation: build output, startup.json logic, visual guides, and code proofs - Publish profile now deletes existing files for clean deploys - No breaking changes: existing startup.json files are preserved - Improves first-run UX, deployment, and cross-platform consistency
416 lines
12 KiB
Markdown
416 lines
12 KiB
Markdown
# 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**
|
|
```bash
|
|
# Linux
|
|
sudo systemctl stop jellyfin
|
|
|
|
# Windows
|
|
net stop JellyfinServer
|
|
|
|
# Docker
|
|
docker stop jellyfin
|
|
```
|
|
|
|
2. **Edit database.xml**
|
|
|
|
Change this line:
|
|
```xml
|
|
<DatabaseType>Jellyfin-SQLite</DatabaseType>
|
|
```
|
|
|
|
To:
|
|
```xml
|
|
<DatabaseType>Jellyfin-PostgreSQL</DatabaseType>
|
|
```
|
|
|
|
3. **Add PostgreSQL connection settings** (uncomment and configure):
|
|
```xml
|
|
<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**
|
|
```bash
|
|
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
|
|
<?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:**
|
|
```xml
|
|
<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:**
|
|
```xml
|
|
<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:**
|
|
```xml
|
|
<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:**
|
|
```xml
|
|
<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
|
|
<?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
|
|
<?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
|
|
<?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**
|
|
```bash
|
|
cp jellyfin.db jellyfin.db.backup
|
|
```
|
|
|
|
2. **Set up PostgreSQL server and create database**
|
|
```sql
|
|
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
|
|
```bash
|
|
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](FILE_BASED_STARTUP_CONFIG.md) - Path configuration
|
|
- [TROUBLESHOOTING_EF_PENDING_CHANGES.md](TROUBLESHOOTING_EF_PENDING_CHANGES.md) - Database migration issues
|
|
- [startup.json.example](startup.json.example) - Path configuration template
|
|
- [database.xml.example](database.xml.example) - Database configuration template
|