# Database Configuration Migration Guide

## Overview
Jellyfin has transitioned from XML-based (`database.xml`) to JSON-based (`database.json`) configuration for database settings. This provides better support for interface types, cleaner syntax, and improved maintainability.

## Backward Compatibility
**The system is fully backward compatible.** If you have an existing `database.xml` file, Jellyfin will continue to work without any changes needed. The configuration loader automatically:

1. Checks for `database.json` first
2. Falls back to `database.xml` if JSON doesn't exist
3. Creates default configuration files as needed

## Migration Options

### Option 1: Automatic Migration (Recommended)
Simply rename or create a new `database.json` file in your Jellyfin configuration directory. The old `database.xml` will continue to work as a fallback.

### Option 2: Manual Migration
If you want to migrate from `database.xml` to `database.json`:

1. **Backup your existing configuration:**
   ```bash
   cp /path/to/config/database.xml /path/to/config/database.xml.backup
   ```

2. **Create a new `database.json`:**
   Use the provided `database.json.example` as a template and copy it to `database.json`:
   ```bash
   cp database.json.example /path/to/config/database.json
   ```

3. **Edit `database.json`** with your specific settings:
   - Update the `connectionString` with your database credentials
   - Adjust `backupOptions` if using PostgreSQL
   - Keep any custom provider settings

4. **Test the new configuration:**
   Start Jellyfin and verify it connects successfully to your database in the logs.

5. **Remove the old file (optional):**
   Once confirmed working, you can remove `database.xml`:
   ```bash
   rm /path/to/config/database.xml
   ```

## Format Differences

### XML Format (Legacy)
```xml
<?xml version="1.0" encoding="utf-8"?>
<DatabaseConfigurationOptions>
  <DatabaseType>Jellyfin-PostgreSQL</DatabaseType>
  <LockingBehavior>NoLock</LockingBehavior>
  <CustomProviderOptions>
	<PluginName>Jellyfin-PostgreSQL</PluginName>
	...
  </CustomProviderOptions>
</DatabaseConfigurationOptions>
```

### JSON Format (Current)
```json
{
  "databaseType": "Jellyfin-PostgreSQL",
  "lockingBehavior": "NoLock",
  "customProviderOptions": {
	"pluginName": "Jellyfin-PostgreSQL",
	...
  }
}
```

## Configuration File Location

The configuration file should be placed in your Jellyfin configuration directory:

- **Linux:** `/etc/jellyfin/` or `~/.config/jellyfin/`
- **Windows:** `%APPDATA%\jellyfin\`
- **Docker:** `/config/` (mounted volume)

## Key Differences

| Feature | XML | JSON |
|---------|-----|------|
| Supports interfaces | ❌ | ✅ |
| Human-readable | ✅ | ✅ |
| Backward compatible | ✅ | ✅ (via fallback) |
| Easier parsing | ❌ | ✅ |

## Troubleshooting

### Error: "Error loading configuration file"
- Ensure the JSON file is valid JSON (use a JSON validator)
- Check file permissions (must be readable by Jellyfin process)
- Verify the configuration path is correct

### Fallback to XML
If you see logs indicating XML deserialization, this means:
- No `database.json` file was found
- The system is using the existing `database.xml` as fallback
- This is normal and expected during migration

### Performance Note
JSON parsing is faster than XML, so you may see slight improvements after migration.

## Support

For issues related to database configuration:
1. Check that your JSON syntax is valid
2. Verify database connection settings
3. Review Jellyfin logs for detailed error messages
4. Keep a backup of your working configuration
