Add troubleshooting section for 57P01 connection termination errors

README-POSTGRESQL.md

@@ -398,6 +398,108 @@ psql -h your-server -U jellyfin -d jellyfin -f jellyfin_backup.sql
 
 ---
 
+## Troubleshooting Connection Issues
+
+### Error: `57P01: terminating connection due to administrator command`
+
+**Cause**: PostgreSQL server forcibly terminated the connection during an operation
+
+**Common reasons**:
+- PostgreSQL server restart or reload
+- Connection timeout (statement_timeout, idle_in_transaction_session_timeout)
+- Manual connection termination via `pg_terminate_backend()`
+- Network instability or firewall issues
+- Resource limits exceeded (max_connections, memory pressure)
+
+**Solutions**:
+
+#### 1. Configure Automatic Retry (Already Enabled)
+
+Jellyfin now includes automatic retry logic for transient failures:
+- **Max retries**: 3 attempts
+- **Max delay**: 5 seconds between retries
+- **Retryable errors**: Includes `57P01` (connection termination)
+
+#### 2. Increase PostgreSQL Timeouts
+
+Edit PostgreSQL configuration (`/etc/postgresql/*/main/postgresql.conf`):
+
+```
+# Increase statement timeout
+statement_timeout = 300000              # 5 minutes (in milliseconds)
+
+# Increase idle transaction timeout
+idle_in_transaction_session_timeout = 600000  # 10 minutes
+
+# Enable TCP keepalives (prevent network timeouts)
+tcp_keepalives_idle = 60                # seconds
+tcp_keepalives_interval = 10            # seconds
+tcp_keepalives_count = 6
+```
+
+Reload PostgreSQL:
+```bash
+sudo systemctl reload postgresql
+# OR
+psql -U postgres -c "SELECT pg_reload_conf();"
+```
+
+#### 3. Optimize Connection String
+
+Add keepalive and timeout parameters to your connection string:
+
+```xml
+<ConnectionString>Host=192.168.129.253;Port=5432;Database=jellyfin;Username=jellyfin;Password=yourpass;Pooling=True;Minimum Pool Size=0;Maximum Pool Size=50;Connection Idle Lifetime=300;Connection Pruning Interval=10;Timeout=30;Command Timeout=300;Keepalive=60</ConnectionString>
+```
+
+**Key parameters**:
+- `Timeout=30` - Connection establishment timeout (30 seconds)
+- `Command Timeout=300` - Query execution timeout (5 minutes)
+- `Keepalive=60` - TCP keepalive interval (60 seconds)
+- `Connection Idle Lifetime=300` - Close idle connections after 5 minutes
+- `Connection Pruning Interval=10` - Check for stale connections every 10 seconds
+
+#### 4. Check PostgreSQL Logs
+
+On your PostgreSQL server:
+
+```bash
+# View recent logs
+sudo tail -f /var/log/postgresql/postgresql-*.log
+
+# Or check systemd journal
+sudo journalctl -u postgresql -n 100 --no-pager
+```
+
+Look for:
+- `received fast shutdown request`
+- `terminating connection`
+- `too many connections`
+- `out of memory`
+
+#### 5. Monitor Active Connections
+
+```sql
+-- Check current connections
+SELECT 
+    datname, 
+    usename, 
+    application_name,
+    state,
+    state_change
+FROM pg_stat_activity
+WHERE datname = 'jellyfin'
+ORDER BY state_change DESC;
+
+-- Check connection limits
+SELECT 
+    (SELECT setting::int FROM pg_settings WHERE name = 'max_connections') AS max_connections,
+    (SELECT COUNT(*) FROM pg_stat_activity) AS current_connections,
+    (SELECT COUNT(*) FROM pg_stat_activity WHERE datname = 'jellyfin') AS jellyfin_connections;
+```
+
+---
+
 ## Building from Source
 
 ```bash