# Increasing Database Command Timeout

## Problem

Slow queries may timeout after 30 seconds (the default PostgreSQL command timeout), causing errors like:

```
Failed executing DbCommand ("30,024"ms) ... CommandTimeout='30'
```

## Solution

The command timeout is configured in the PostgreSQL connection string, which is built from the database configuration file.

### Step 1: Locate Database Configuration

The database configuration is stored in:
```
<ConfigDir>/database.json
```

For example:
- Linux: `/etc/jellyfin/database.json`
- Windows: `C:/ProgramData/jellyfin/config/database.json`

### Step 2: Add Command Timeout Option

Edit `database.json` and add the `command-timeout` option:

```json
{
  "DatabaseType": "Jellyfin-PostgreSQL",
  "LockingBehavior": "NoLock",
  "CustomProviderOptions": {
    "Options": [
      {
        "Key": "host",
        "Value": "localhost"
      },
      {
        "Key": "port",
        "Value": "5432"
      },
      {
        "Key": "database",
        "Value": "jellyfin"
      },
      {
        "Key": "username",
        "Value": "jellyfin"
      },
      {
        "Key": "password",
        "Value": "your_password_here"
      },
      {
        "Key": "command-timeout",
        "Value": "120"
      }
    ]
  }
}
```

### Available Timeout Options

| Option | Default | Unit | Description |
|--------|---------|------|-------------|
| `command-timeout` | 30 | seconds | Maximum time for a query to execute |
| `connection-timeout` | 15 | seconds | Maximum time to establish connection |

### Recommended Values

**For Development/Testing:**
```json
{
  "Key": "command-timeout",
  "Value": "120"
}
```
- Allows up to 2 minutes for complex queries
- Good for debugging slow queries

**For Production:**
```json
{
  "Key": "command-timeout",
  "Value": "60"
}
```
- Balances between allowing reasonable query time and failing fast on problems
- Prevents hanging connections

### Step 3: Restart Jellyfin

```bash
# Linux (systemd)
sudo systemctl restart jellyfin

# Or if running manually
# Stop Jellyfin and restart
```

### Step 4: Verify Configuration

Check the logs on startup to see the applied timeout:

```
[INF] PostgreSQL connection: Host=localhost, Port=5432, ...
```

The command timeout is applied to all database commands. You can verify it's working by checking slow query logs:

```
[ERR] Failed executing DbCommand ("45,123"ms) ... CommandTimeout='120'
```

## Alternative: Set via Connection String Directly

If you're configuring PostgreSQL via connection string (advanced), you can set it there:

```
Host=localhost;Database=jellyfin;Username=jellyfin;Password=***;Command Timeout=120;
```

## When to Increase Timeout

✅ **Increase timeout if:**
- Queries are legitimately slow due to large datasets
- You're running complex analytics or reporting queries
- Temporary workaround while optimizing queries

❌ **Don't increase timeout if:**
- Queries should be fast but aren't (fix the query instead)
- Most queries complete quickly (one slow query affects all)
- Timeout masks underlying performance issues

## Better Solutions

Instead of just increasing timeout, consider:

1. **Add Database Indexes** (see `sql/add-performance-indexes.sql`)
2. **Optimize Query Logic** (see `docs/query-grouping-current-status.md`)
3. **Use Application-Level Filtering** (avoid grouping in database)
4. **Upgrade EF Core** (when using stable .NET version)

## Monitoring

After changing timeout, monitor query performance:

```sql
-- Run on PostgreSQL to see slow queries
SELECT 
    pid,
    now() - query_start AS duration,
    LEFT(query, 100) AS query_preview
FROM pg_stat_activity
WHERE state != 'idle'
  AND query NOT LIKE '%pg_stat_activity%'
  AND (now() - query_start) > interval '5 seconds'
ORDER BY duration DESC;
```

See `sql/monitor-query-performance.sql` for comprehensive monitoring queries.

## Current Query Performance Issue

The grouping queries in `BaseItemRepository.ApplyGroupingFilter` currently generate correlated subqueries that can be slow. Until EF Core translation improves, the options are:

1. **Increase timeout** (this guide)
2. **Add indexes** (`sql/add-performance-indexes.sql`)  
3. **Disable grouping** (application-level fix)

See `docs/query-grouping-current-status.md` for full details and all workaround options.