pgsql-jellyfin/docs/POSTGRES_BACKUP_LOGGING_EXTERNAL_TOOLS.md

PostgreSQL Backup Logging - External Tool References

Overview

All logging messages have been updated to explicitly clarify that pg_dump and pg_restore are external command-line tools being executed as separate processes, not internal library functions.

Updated Log Messages

PostgresBackupService.cs

Backup Creation:

// Before:
"Starting PostgreSQL backup to {BackupPath}"
"Executing: {PgDump} {Arguments}"
"Successfully created PostgreSQL backup at {BackupPath}"

// After:
"Starting PostgreSQL backup using external pg_dump tool to {BackupPath}"
"Executing external command: {PgDump} {Arguments}"
"Successfully created PostgreSQL backup using external pg_dump at {BackupPath}"

Backup Restoration:

// Before:
"Starting PostgreSQL restore from {BackupPath}"
"Successfully restored PostgreSQL backup from {BackupPath}"

// After:
"Starting PostgreSQL restore using external pg_restore tool from {BackupPath}"
"Successfully restored PostgreSQL backup using external pg_restore from {BackupPath}"

Backup Deletion:

// Before (in PostgresDatabaseProvider):
"Deleted local PostgreSQL backup: {BackupPath}"

// After:
"Deleted local PostgreSQL backup created by external pg_dump: {BackupPath}"

Error Messages:

// Before:
"{defaultExecutableName} executable not found. Please configure the path in database.xml or ensure it's in the system PATH."

// After:
"External {defaultExecutableName} executable not found. Please configure the path in database.xml or ensure PostgreSQL client tools are installed and in the system PATH."

PostgresDatabaseProvider.cs

Initialization Messages:

// Before:
"PostgreSQL backup service initialized for local database"
"PostgreSQL database is on remote server ({Host}). Backup operations via pg_dump/pg_restore are disabled"

// After:
"PostgreSQL backup service initialized for local database (will use external pg_dump/pg_restore tools)"
"PostgreSQL database is on remote server ({Host}). Backup operations via external pg_dump/pg_restore tools are disabled"

Backup Operation Messages:

// Before:
"PostgreSQL local backup created: {BackupPath}"
"Failed to create local PostgreSQL backup using pg_dump"
"Fast backup is not implemented for PostgreSQL on a remote server. Use pg_dump manually..."

// After:
"PostgreSQL local backup created using external pg_dump: {BackupPath}"
"Failed to create local PostgreSQL backup using external pg_dump"
"Fast backup is not implemented for PostgreSQL on a remote server. Use external pg_dump command manually..."

Restore Operation Messages:

// Before:
"PostgreSQL local backup restored from: {BackupPath}"
"Failed to restore local PostgreSQL backup using pg_restore"
"Fast restore is not implemented for PostgreSQL on a remote server. Use pg_restore manually..."

// After:
"PostgreSQL local backup restored using external pg_restore from: {BackupPath}"
"Failed to restore local PostgreSQL backup using external pg_restore"
"Fast restore is not implemented for PostgreSQL on a remote server. Use external pg_restore command manually..."

Delete Operation Messages:

// Before:
"Failed to delete local PostgreSQL backup: {BackupKey}"
"Backup deletion is not implemented for PostgreSQL on a remote server. Manage backups externally."

// After:
"Failed to delete local PostgreSQL backup created by external pg_dump: {BackupKey}"
"Backup deletion is not implemented for PostgreSQL on a remote server. Manage backups created by external pg_dump/pg_restore manually."

Complete Log Flow Examples

Successful Local Backup:

[INFO] PostgreSQL backup service initialized for local database (will use external pg_dump/pg_restore tools)
[INFO] Starting PostgreSQL backup using external pg_dump tool to /data/backups/jellyfin_postgres_backup_20250128_143022.dump
[DEBUG] Executing external command: pg_dump -h localhost -p 5432 -U jellyfin -d jellyfin -F c -Z 6 -b -v -f "/data/backups/jellyfin_postgres_backup_20250128_143022.dump"
[INFO] Successfully created PostgreSQL backup using external pg_dump at /data/backups/jellyfin_postgres_backup_20250128_143022.dump (15728640 bytes)
[INFO] PostgreSQL local backup created using external pg_dump: /data/backups/jellyfin_postgres_backup_20250128_143022.dump

Successful Local Restore:

[INFO] Starting PostgreSQL restore using external pg_restore tool from /data/backups/jellyfin_postgres_backup_20250128_143022.dump
[INFO] Successfully restored PostgreSQL backup using external pg_restore from /data/backups/jellyfin_postgres_backup_20250128_143022.dump
[INFO] PostgreSQL local backup restored using external pg_restore from: /data/backups/jellyfin_postgres_backup_20250128_143022.dump

Successful Local Delete:

[INFO] Deleted local PostgreSQL backup created by external pg_dump: /data/backups/jellyfin_postgres_backup_20250128_143022.dump

Remote Database (Backups Disabled):

[INFO] PostgreSQL database is on remote server (db.example.com). Backup operations via external pg_dump/pg_restore tools are disabled
[WARN] Fast backup is not implemented for PostgreSQL on a remote server. Use external pg_dump command manually for proper backups.

Error: External Tool Not Found:

[ERROR] External pg_dump executable not found. Please configure the path in database.xml or ensure PostgreSQL client tools are installed and in the system PATH.

Benefits of Updated Messaging

1. Clarity: Users understand that these are external processes, not built-in functionality
2. Troubleshooting: Makes it clear that PostgreSQL client tools must be installed
3. Expectations: Sets proper expectations about what the system is doing
4. Documentation: Helps users understand the requirement for external dependencies
5. Transparency: Makes the technical implementation more transparent

Technical Details

• Process Execution: System.Diagnostics.Process.Start() is used to launch pg_dump/pg_restore
• Environment Variables: PGPASSWORD is set in the process environment for authentication
• Standard Output/Error: Captured for logging and error handling
• Working Directory: Backup files are created in the Jellyfin data directory
• Timeout Handling: Configurable timeout prevents hung processes

For Users

These updated messages help users understand that:

1. Jellyfin requires PostgreSQL client tools to be installed
2. The backup functionality calls out to external commands
3. Path configuration in database.xml points to actual executables
4. Error messages about missing executables mean the tools need to be installed

For Developers

The updated logging makes it clear:

1. We're using process execution, not a library
2. External dependencies are required
3. Configuration affects external tool execution
4. Debugging should include checking if tools are in PATH or configured correctly