feat: add scheduled arr cleanup with per-instance settings

Author: santiagosayshey

src/lib/server/db/migrations.ts

@@ -53,6 +53,7 @@ import { migration as migration048 } from './migrations/048_fix_sync_database_fo
 import { migration as migration049 } from './migrations/049_create_job_queue.ts';
 import { migration as migration050 } from './migrations/050_remove_dry_run_columns.ts';
 import { migration as migration051 } from './migrations/051_cron_scheduling.ts';
+import { migration as migration052 } from './migrations/052_create_arr_cleanup_settings.ts';
 
 export interface Migration {
 	version: number;
@@ -324,7 +325,8 @@ export function loadMigrations(): Migration[] {
 		migration048,
 		migration049,
 		migration050,
-		migration051
+		migration051,
+		migration052
 	];
 
 	// Sort by version number

src/lib/server/db/migrations/052_create_arr_cleanup_settings.ts

@@ -0,0 +1,34 @@
+import type { Migration } from '../migrations.ts';
+
+/**
+ * Migration 052: Create arr_cleanup_settings table
+ *
+ * Stores per-instance cleanup scheduling config.
+ * Cleanup removes stale synced configs and media flagged as removed from TMDB/TVDB.
+ */
+
+export const migration: Migration = {
+	version: 52,
+	name: 'Create arr_cleanup_settings table',
+
+	up: `
+		CREATE TABLE arr_cleanup_settings (
+			id INTEGER PRIMARY KEY AUTOINCREMENT,
+			arr_instance_id INTEGER NOT NULL UNIQUE,
+			enabled INTEGER NOT NULL DEFAULT 0,
+			cron TEXT NOT NULL DEFAULT '0 0 * * 0',
+			next_run_at TEXT,
+			last_run_at TEXT,
+			created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+			updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+			FOREIGN KEY (arr_instance_id) REFERENCES arr_instances(id) ON DELETE CASCADE
+		);
+
+		CREATE INDEX idx_arr_cleanup_settings_instance ON arr_cleanup_settings(arr_instance_id);
+	`,
+
+	down: `
+		DROP INDEX IF EXISTS idx_arr_cleanup_settings_instance;
+		DROP TABLE IF EXISTS arr_cleanup_settings;
+	`
+};

src/lib/server/db/queries/arrCleanupSettings.ts

@@ -0,0 +1,147 @@
+import { db } from '../db.ts';
+
+interface CleanupSettingsRow {
+	id: number;
+	arr_instance_id: number;
+	enabled: number;
+	cron: string;
+	next_run_at: string | null;
+	last_run_at: string | null;
+	created_at: string;
+	updated_at: string;
+}
+
+export interface CleanupSettings {
+	id: number;
+	arrInstanceId: number;
+	enabled: boolean;
+	cron: string;
+	nextRunAt: string | null;
+	lastRunAt: string | null;
+	createdAt: string;
+	updatedAt: string;
+}
+
+export interface CleanupSettingsInput {
+	enabled?: boolean;
+	cron?: string;
+}
+
+function rowToSettings(row: CleanupSettingsRow): CleanupSettings {
+	return {
+		id: row.id,
+		arrInstanceId: row.arr_instance_id,
+		enabled: row.enabled === 1,
+		cron: row.cron,
+		nextRunAt: row.next_run_at,
+		lastRunAt: row.last_run_at,
+		createdAt: row.created_at,
+		updatedAt: row.updated_at
+	};
+}
+
+export const arrCleanupSettingsQueries = {
+	getByInstanceId(arrInstanceId: number): CleanupSettings | undefined {
+		const row = db.queryFirst<CleanupSettingsRow>(
+			'SELECT * FROM arr_cleanup_settings WHERE arr_instance_id = ?',
+			arrInstanceId
+		);
+		return row ? rowToSettings(row) : undefined;
+	},
+
+	getAll(): CleanupSettings[] {
+		const rows = db.query<CleanupSettingsRow>('SELECT * FROM arr_cleanup_settings');
+		return rows.map(rowToSettings);
+	},
+
+	getEnabled(): CleanupSettings[] {
+		const rows = db.query<CleanupSettingsRow>(
+			'SELECT * FROM arr_cleanup_settings WHERE enabled = 1'
+		);
+		return rows.map(rowToSettings);
+	},
+
+	upsert(arrInstanceId: number, input: CleanupSettingsInput): CleanupSettings {
+		const existing = this.getByInstanceId(arrInstanceId);
+
+		if (existing) {
+			this.update(arrInstanceId, input);
+			return this.getByInstanceId(arrInstanceId)!;
+		}
+
+		const enabled = input.enabled !== undefined ? (input.enabled ? 1 : 0) : 0;
+		const cron = input.cron ?? '0 0 * * 0';
+
+		db.execute(
+			`INSERT INTO arr_cleanup_settings (arr_instance_id, enabled, cron) VALUES (?, ?, ?)`,
+			arrInstanceId,
+			enabled,
+			cron
+		);
+
+		return this.getByInstanceId(arrInstanceId)!;
+	},
+
+	update(arrInstanceId: number, input: CleanupSettingsInput): boolean {
+		const updates: string[] = [];
+		const params: (string | number | null)[] = [];
+
+		if (input.enabled !== undefined) {
+			updates.push('enabled = ?');
+			params.push(input.enabled ? 1 : 0);
+		}
+		if (input.cron !== undefined) {
+			updates.push('cron = ?');
+			params.push(input.cron);
+		}
+
+		if (updates.length === 0) {
+			return false;
+		}
+
+		updates.push('updated_at = CURRENT_TIMESTAMP');
+		params.push(arrInstanceId);
+
+		const affected = db.execute(
+			`UPDATE arr_cleanup_settings SET ${updates.join(', ')} WHERE arr_instance_id = ?`,
+			...params
+		);
+
+		return affected > 0;
+	},
+
+	delete(arrInstanceId: number): boolean {
+		const affected = db.execute(
+			'DELETE FROM arr_cleanup_settings WHERE arr_instance_id = ?',
+			arrInstanceId
+		);
+		return affected > 0;
+	},
+
+	updateLastRun(arrInstanceId: number): void {
+		db.execute(
+			'UPDATE arr_cleanup_settings SET last_run_at = CURRENT_TIMESTAMP, updated_at = CURRENT_TIMESTAMP WHERE arr_instance_id = ?',
+			arrInstanceId
+		);
+	},
+
+	updateNextRunAt(arrInstanceId: number, nextRunAt: string | null): void {
+		db.execute(
+			'UPDATE arr_cleanup_settings SET next_run_at = ?, updated_at = CURRENT_TIMESTAMP WHERE arr_instance_id = ?',
+			nextRunAt,
+			arrInstanceId
+		);
+	},
+
+	getDueConfigs(): CleanupSettings[] {
+		const rows = db.query<CleanupSettingsRow>(`
+			SELECT * FROM arr_cleanup_settings
+			WHERE enabled = 1
+			AND (
+				next_run_at IS NULL
+				OR datetime('now') >= datetime(replace(replace(next_run_at, 'T', ' '), 'Z', ''))
+			)
+		`);
+		return rows.map(rowToSettings);
+	}
+};

src/lib/server/db/schema.sql

@@ -1,7 +1,7 @@
 -- Profilarr Database Schema
 -- This file documents the current database schema after all migrations
 -- DO NOT execute this file directly - use migrations instead
--- Last updated: 2026-01-28
+-- Last updated: 2026-02-20
 
 -- ==============================================================================
 -- TABLE: migrations
@@ -276,7 +276,7 @@ CREATE TABLE database_instances (
 -- ==============================================================================
 -- TABLE: upgrade_configs
 -- Purpose: Store upgrade configuration per arr instance for automated quality upgrades
--- Migration: 011_create_upgrade_configs.ts, 012_add_upgrade_last_run.ts, 013_add_upgrade_dry_run.ts
+-- Migration: 011_create_upgrade_configs.ts, 012_add_upgrade_last_run.ts, 013_add_upgrade_dry_run.ts, 051_cron_scheduling.ts
 -- ==============================================================================
 
 CREATE TABLE upgrade_configs (
@@ -288,7 +288,7 @@ CREATE TABLE upgrade_configs (
     -- Core settings
     enabled INTEGER NOT NULL DEFAULT 0,         -- Master on/off switch
     dry_run INTEGER NOT NULL DEFAULT 0,         -- 1=dry run mode, 0=normal (Migration 013)
-    schedule INTEGER NOT NULL DEFAULT 360,      -- Run interval in minutes (default 6 hours)
+    cron TEXT NOT NULL DEFAULT '0 */6 * * *',   -- Cron expression (Migration 051, replaced schedule)
     filter_mode TEXT NOT NULL DEFAULT 'round_robin', -- 'round_robin' or 'random'
 
     -- Filters (stored as JSON array of FilterConfig objects)
@@ -297,6 +297,7 @@ CREATE TABLE upgrade_configs (
     -- State tracking
     current_filter_index INTEGER NOT NULL DEFAULT 0, -- For round-robin mode
     last_run_at DATETIME,                            -- When upgrade job last ran (Migration 012)
+    next_run_at TEXT,                                -- Next scheduled run (Migration 051)
 
     -- Metadata
     created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
@@ -614,7 +615,7 @@ CREATE INDEX idx_pattern_match_cache_created_at ON pattern_match_cache(created_a
 -- ==============================================================================
 -- TABLE: arr_rename_settings
 -- Purpose: Store rename configuration per arr instance for bulk file/folder renaming
--- Migration: 024_create_arr_rename_settings.ts, 025_add_rename_notification_mode.ts
+-- Migration: 024_create_arr_rename_settings.ts, 025_add_rename_notification_mode.ts, 051_cron_scheduling.ts
 -- ==============================================================================
 
 CREATE TABLE arr_rename_settings (
@@ -631,7 +632,8 @@ CREATE TABLE arr_rename_settings (
 
     -- Job scheduling
     enabled INTEGER NOT NULL DEFAULT 0,         -- Master on/off switch for scheduled job
-    schedule INTEGER NOT NULL DEFAULT 1440,     -- Run interval in minutes (default 24 hours)
+    cron TEXT NOT NULL DEFAULT '0 0 * * *',     -- Cron expression (Migration 051, replaced schedule)
+    next_run_at TEXT,                           -- Next scheduled run (Migration 051)
     last_run_at DATETIME,                       -- When rename job last ran
 
     -- Metadata
@@ -644,6 +646,36 @@ CREATE TABLE arr_rename_settings (
 -- Arr rename settings indexes (Migration: 024_create_arr_rename_settings.ts)
 CREATE INDEX idx_arr_rename_settings_arr_instance ON arr_rename_settings(arr_instance_id);
 
+-- ==============================================================================
+-- TABLE: arr_cleanup_settings
+-- Purpose: Store cleanup scheduling configuration per arr instance
+-- Migration: 052_create_arr_cleanup_settings.ts
+-- ==============================================================================
+
+CREATE TABLE arr_cleanup_settings (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+
+    -- Relationship (one config per arr instance)
+    arr_instance_id INTEGER NOT NULL UNIQUE,
+
+    -- Settings
+    enabled INTEGER NOT NULL DEFAULT 0,         -- Master on/off switch
+    cron TEXT NOT NULL DEFAULT '0 0 * * 0',     -- Cron expression (default: weekly Sunday midnight)
+
+    -- State tracking
+    next_run_at TEXT,                           -- Next scheduled run
+    last_run_at TEXT,                           -- When cleanup job last ran
+
+    -- Metadata
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+
+    FOREIGN KEY (arr_instance_id) REFERENCES arr_instances(id) ON DELETE CASCADE
+);
+
+-- Arr cleanup settings indexes (Migration: 052_create_arr_cleanup_settings.ts)
+CREATE INDEX idx_arr_cleanup_settings_instance ON arr_cleanup_settings(arr_instance_id);
+
 -- ==============================================================================
 -- TABLE: upgrade_runs
 -- Purpose: Store upgrade run history for each arr instance
@@ -665,7 +697,7 @@ CREATE TABLE upgrade_runs (
     dry_run INTEGER NOT NULL DEFAULT 0,         -- 1=dry run, 0=live
 
     -- Config snapshot (flat for queryability)
-    schedule INTEGER NOT NULL,                  -- Schedule interval in minutes
+    cron TEXT NOT NULL,                         -- Cron expression (Migration 051, renamed from schedule)
     filter_mode TEXT NOT NULL,                  -- 'round_robin' or 'random'
     filter_name TEXT NOT NULL,                  -- Name of the filter used
 

src/lib/server/jobs/cleanup.ts

@@ -21,7 +21,8 @@ export function cleanupJobsForArrInstance(instanceId: number): number {
 		'arr.sync',
 		'arr.sync.qualityProfiles',
 		'arr.sync.delayProfiles',
-		'arr.sync.mediaManagement'
+		'arr.sync.mediaManagement',
+		'arr.cleanup'
 	];
 
 	const jobs = jobQueueQueries.listByJobTypes(jobTypes);

src/lib/server/jobs/display.ts

@@ -21,6 +21,8 @@ export function formatJobTypeLabel(jobType: JobType): string {
 			return 'Arr Rename';
 		case 'arr.upgrade':
 			return 'Arr Upgrade';
+		case 'arr.cleanup':
+			return 'Arr Cleanup';
 		case 'pcd.sync':
 			return 'PCD Sync';
 		case 'backup.create':
@@ -63,7 +65,7 @@ export function buildJobDisplayName(
 	}
 
 	const isArrSync = jobType === 'arr.sync' || jobType.startsWith('arr.sync.');
-	if ((isArrSync || jobType === 'arr.rename' || jobType === 'arr.upgrade') && instanceId !== null) {
+	if ((isArrSync || jobType === 'arr.rename' || jobType === 'arr.upgrade' || jobType === 'arr.cleanup') && instanceId !== null) {
 		const name =
 			lookups?.arrNameById?.get(instanceId) ?? arrInstancesQueries.getById(instanceId)?.name;
 		return name ? `${base} - ${name}` : base;