profilarr/docs/backend/upgrades.md

Upgrades

Source: src/lib/server/upgrades/ (processor, cooldown, normalize, logger) Shared: src/lib/shared/upgrades/ (filters, selectors)

The upgrade system is a scheduled job that proactively searches Arr for better releases. It fills the gap that RSS alone can't cover: new quality profiles, profile score updates, and indexer downtime all leave existing library items with suboptimal files that RSS will never revisit. Upgrades work through the library methodically, one filter at a time, searching for improvements and letting Arr's own upgrade logic decide whether to grab them.

Table of Contents

• Pipeline
• Filters
• Selectors
• Scheduling
• Cooldown
• Dry Run
• Logging
• Notifications

Pipeline

Each run processes a single filter from the config's filter list. The processor normalizes Radarr/Sonarr responses into a unified UpgradeItem so all downstream logic is app-agnostic.

flowchart TD
    FETCH[Fetch library + normalize] --> PICK[Pick filter]
    PICK --> EVAL[Evaluate filter rules]
    EVAL --> COOL[Exclude cooldown-tagged items]
    COOL --> DRY{Dry run?}

    DRY -->|Yes| EXCL[Exclude previous dry-run picks]
    DRY -->|No| SEL

    EXCL --> SEL[Apply selector]
    SEL --> SEARCH{Dry run?}

    SEARCH -->|Yes| RELEASES[Fetch releases + compare scores]
    SEARCH -->|No| BATCH[Batch search + apply cooldown tag]

    RELEASES --> LOG[Log + notify]
    BATCH --> LOG

Status

Status	Meaning
success	Searches triggered, no errors
partial	Some searches succeeded, some failed
failed	All searches failed or a fatal error occurred
skipped	No items to search (filtered to zero)

Filters

Filters use a nested group/rule structure with AND/OR logic. A config can have multiple filters; each run processes exactly one (see Scheduling).

A rule is a field + operator + value triple:

monitored  is  true
year       gte 2020
status     gte released

A group wraps rules (or nested groups) with a match mode:

• all -- every child must match (AND)
• any -- at least one child must match (OR)

Fields are typed by category:

Category	Operators	Examples
Boolean	is, is_not	monitored, cutoff_met
Text	contains, not_contains, starts/ends_with, eq	title, quality_profile, genres, tags
Number	eq, neq, gt, gte, lt, lte	year, rating, size_on_disk, popularity
Date	before, after, in_last, not_in_last	date_added, digital_release, first_aired
Ordinal	eq, neq, gte, lte, gt, lt	status, minimum_availability

Ordinal fields have a defined progression (e.g. tba -> announced -> inCinemas -> released for Radarr) so operators like gte mean "has reached this stage or later." Radarr and Sonarr each have app-specific fields; the full list is in src/lib/shared/upgrades/filters.ts.

Each filter also carries a cutoff (0-100%), a percentage of the quality profile's cutoff score. Items whose current score meets or exceeds the threshold are considered "cutoff met" and can be filtered out.

Selectors

After filtering, a selector picks which items to search. Each filter specifies a selector strategy and a count (items per run).

Selector	Strategy
random	Shuffle, take N
oldest	Oldest by date added
newest	Newest by date added
lowest_score	Lowest custom format score first
most_popular	Highest popularity first
least_popular	Lowest popularity first
alphabetical_asc	A-Z by title
alphabetical_desc	Z-A by title

Selector definitions live in src/lib/shared/upgrades/selectors.ts.

Scheduling

Each Arr instance has a single upgrade config with a global cron schedule. Each run picks one filter from the enabled list:

• Round robin -- cycles through filters in order. currentFilterIndex increments after each non-failed run and wraps around.
• Random -- shuffles the enabled filters and cycles through all of them before reshuffling.

The job system manages dispatch via nextRunAt / lastRunAt. After each run, the handler calculates the next cron occurrence and updates nextRunAt.

Cooldown

The cooldown system prevents the same item from being searched repeatedly across runs. It works through Arr tags:

1. When items are searched in a live run, the processor tags them in Arr with profilarr-{filter-name} (slugified, max 50 chars). Filters can also specify a custom tag to override the auto-generated one.
2. On the next run, filterByFilterTag() excludes items that already carry the filter's tag.
3. When every matched item has been tagged (the filter is "exhausted"), resetFilterCooldown() removes the tag from all items and a new cycle begins.

This means the system works through the entire filtered pool before revisiting any item. Multiple filters can share a tag to enforce a shared cooldown across them.

Dry Run

Dry-run mode fetches available releases for each selected item and compares scores without triggering actual searches. This lets users preview what the system would do.

An in-memory exclusion cache (1-hour TTL, keyed by instance ID) tracks items selected in previous dry runs so the same items aren't re-picked on repeated manual runs. The cache can be cleared from the UI.

In dry-run mode, cooldown tags are not applied to items.

Logging

Every run produces an UpgradeJobLog that captures the full funnel:

• Config snapshot -- cron, filterMode, selected filter name, dryRun flag
• Library stats -- total items, fetch duration
• Filter stats -- matched count, after cooldown, dry-run excluded
• Selection stats -- method, requested count, actual count, per-item details (title, current score/formats, upgrade releases with scores)
• Results -- searches triggered, successful, failed, errors

Three logging functions in logger.ts:

• logUpgradeRun(log) -- persists the full log to the upgrade_runs table and writes a summary to the logger with source UpgradeJob. Log level is INFO for success, WARN for partial, ERROR for failed.
• logUpgradeSkipped(instanceId, name, reason) -- DEBUG-level.
• logUpgradeError(instanceId, name, error) -- ERROR-level.

Notifications

Upgrade runs emit one of four notification types via the notification system:

Type	Severity	When
upgrade.success	success	Searches completed, no errors
upgrade.partial	warning	Some searches, some errors
upgrade.failed	error	All searches failed
upgrade.skipped	success	Nothing to search

Notifications are not sent for dry runs. Each notification includes the filter name, selector method, funnel breakdown (total -> filtered -> cooldown -> selected), and per-item score/format comparisons with poster images. Sonarr items are flattened by season.