diff --git a/README-POSTGRESQL.md b/README-POSTGRESQL.md new file mode 100644 index 00000000..3f819f20 --- /dev/null +++ b/README-POSTGRESQL.md @@ -0,0 +1,381 @@ +# 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: + +```bash +sudo apt-get update +sudo apt-get install -y \ + libfontconfig1 \ + libfreetype6 \ + libssl3 \ + libicu-dev +``` + +#### RHEL/CentOS/Fedora-based systems: + +```bash +sudo dnf install -y \ + fontconfig \ + freetype \ + openssl \ + libicu +``` + +#### Arch Linux: + +```bash +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**: +```bash +sudo apt-get install -y postgresql-client +``` + +**RHEL/CentOS/Fedora**: +```bash +sudo dnf install -y postgresql +``` + +**Verify psql is available**: +```bash +psql --version +``` + +--- + +## Database Configuration + +### Option 1: Using ConnectionString (Recommended) + +Create or edit `config/database.xml` in your Jellyfin data directory: + +```xml + + + Jellyfin-PostgreSQL + NoLock + + + Jellyfin-PostgreSQL + Jellyfin.Database.Providers.Postgres + + + Host=192.168.1.100;Port=5432;Database=jellyfin;Username=jellyfin;Password=your_password_here + + + + + pg_dump + pg_restore + custom + true + 6 + 1800 + true + + +``` + +### Option 2: Using Individual Options + +```xml + + + Jellyfin-PostgreSQL + + + Jellyfin-PostgreSQL + Jellyfin.Database.Providers.Postgres + + + + Host + 192.168.1.100 + + + + Port + 5432 + + + + Database + jellyfin + + + + Username + jellyfin + + + + Password + your_password_here + + + + +``` + +### Option 3: Hybrid (ConnectionString + Overrides) + +Individual options take precedence over ConnectionString: + +```xml + + + Host=192.168.1.100;Port=5432;Database=jellyfin;Username=jellyfin + + + + + Password + production_password + + + +``` + +--- + +## 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: + +```bash +# 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**: +```bash +# 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**: +```bash +# 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**: +```bash +# 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`: + +```xml + + pg_dump + custom + 6 + +``` + +**Works for both local and remote databases!** + +### Manual Backup + +```bash +# 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 + +```bash +# 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 + +```bash +# 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](https://github.com/jellyfin/jellyfin) with PostgreSQL support and .NET 11 compatibility.