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:
```csharp
// 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:
```csharp
// 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:
```csharp
// Before (in PostgresDatabaseProvider):
"Deleted local PostgreSQL backup: {BackupPath}"

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

#### Error Messages:
```csharp
// 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:
```csharp
// 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:
```csharp
// 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:
```csharp
// 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:
```csharp
// 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