From 69fe460538a2df7e21ec4010f99cfb855132c971 Mon Sep 17 00:00:00 2001
From: Erik Darling <2136037+erikdarlingdata@users.noreply.github.com>
Date: Mon, 27 Apr 2026 20:11:56 -0400
Subject: [PATCH] Add Purge Now action to Manage Servers (#900)

- New "Purge Now" button on Manage Servers window with override modes
  (configured / 1 / 3 / 7 / custom / all). All option uses TRUNCATE.
- Right-click menu now mirrors all per-row actions (Edit, Toggle Favorite,
  Check Server Version, Purge Now, Remove) above existing copy/export.
- config.data_retention reworked: @retention_days = NULL respects per-collector
  schedule, 0 TRUNCATEs every collect.* table, N > 0 overrides every cutoff
  to N days. Old @truncate_all parameter removed; @retention_days = 0 covers
  that case. Truncate path snapshots row count before wiping for reporting.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 Dashboard/ManageServersWindow.xaml    |   8 +
 Dashboard/ManageServersWindow.xaml.cs |  67 ++++++++
 Dashboard/PurgeNowDialog.xaml         |  53 ++++++
 Dashboard/PurgeNowDialog.xaml.cs      | 114 +++++++++++++
 Dashboard/Services/ServerManager.cs   |  88 ++++++++++
 install/43_data_retention.sql         | 226 +++++++++++++++++++++-----
 6 files changed, 515 insertions(+), 41 deletions(-)
 create mode 100644 Dashboard/PurgeNowDialog.xaml
 create mode 100644 Dashboard/PurgeNowDialog.xaml.cs

diff --git a/Dashboard/ManageServersWindow.xaml b/Dashboard/ManageServersWindow.xaml
index 99d1650c..c96e9863 100644
--- a/Dashboard/ManageServersWindow.xaml
+++ b/Dashboard/ManageServersWindow.xaml
@@ -9,6 +9,13 @@
     <Window.Resources>
         <BooleanToVisibilityConverter x:Key="BoolToVisibilityConverter"/>
         <ContextMenu x:Key="DataGridContextMenu">
+            <MenuItem Header="Edit..." Click="EditServer_Click"/>
+            <MenuItem Header="Toggle Favorite" Click="ToggleFavorite_Click"/>
+            <MenuItem Header="Check Server Version" Click="CheckForUpdates_Click"/>
+            <MenuItem Header="Purge Now" Click="PurgeNow_Click"/>
+            <MenuItem Header="Remove" Click="RemoveServer_Click"
+                      Foreground="{DynamicResource ErrorBrush}"/>
+            <Separator/>
             <MenuItem Header="Copy Cell" Click="CopyCell_Click">
                 <MenuItem.Icon><TextBlock Text="&#x1F4CB;"/></MenuItem.Icon>
             </MenuItem>
@@ -91,6 +98,7 @@
                 <Button Content="Edit..." Width="80" Height="30" Margin="0,0,8,0" Click="EditServer_Click"/>
                 <Button x:Name="ToggleFavoriteButton" Content="Toggle Favorite" Width="110" Height="30" Margin="0,0,8,0" Click="ToggleFavorite_Click"/>
                 <Button x:Name="CheckUpdatesButton" Content="Check Server Version" Width="140" Height="30" Margin="0,0,8,0" Click="CheckForUpdates_Click"/>
+                <Button Content="Purge Now" Width="100" Height="30" Margin="0,0,8,0" Click="PurgeNow_Click"/>
                 <Button Content="Remove" Width="80" Height="30" Margin="0,0,8,0" Click="RemoveServer_Click"
                         Foreground="{DynamicResource ErrorBrush}"/>
             </StackPanel>
diff --git a/Dashboard/ManageServersWindow.xaml.cs b/Dashboard/ManageServersWindow.xaml.cs
index bbd2ea74..c2ad284c 100644
--- a/Dashboard/ManageServersWindow.xaml.cs
+++ b/Dashboard/ManageServersWindow.xaml.cs
@@ -297,6 +297,73 @@ string Normalize(string v)
             }
         }
 
+        private async void PurgeNow_Click(object sender, RoutedEventArgs e)
+        {
+            if (ServersDataGrid.SelectedItem is not ServerConnection server)
+            {
+                MessageBox.Show(
+                    "Please select a server to purge.",
+                    "No Server Selected",
+                    MessageBoxButton.OK,
+                    MessageBoxImage.Information);
+                return;
+            }
+
+            var dialog = new PurgeNowDialog(server.DisplayNameWithIntent) { Owner = this };
+            if (dialog.ShowDialog() != true) return;
+
+            Cursor = System.Windows.Input.Cursors.Wait;
+            try
+            {
+                var result = await _serverManager.RunDataRetentionAsync(
+                    server,
+                    dialog.RetentionDaysOverride);
+
+                bool wasTruncate = dialog.RetentionDaysOverride == 0;
+                string body;
+                if (wasTruncate)
+                {
+                    body = $"All collector tables truncated.\n\n" +
+                           $"Rows wiped: {result.RowsDeleted:N0}\n" +
+                           $"Tables affected: {result.TableCount}\n" +
+                           $"Status: {result.Status}\n" +
+                           $"Duration: {result.DurationMs} ms";
+                }
+                else
+                {
+                    body = $"Purge complete.\n\n" +
+                           $"Rows deleted: {result.RowsDeleted:N0}\n" +
+                           $"Tables touched: {result.TableCount}\n" +
+                           $"Status: {result.Status}\n" +
+                           $"Duration: {result.DurationMs} ms";
+                }
+
+                if (!string.Equals(result.Status, "SUCCESS", StringComparison.Ordinal) &&
+                    !string.IsNullOrEmpty(result.Message))
+                {
+                    body += $"\n\nMessage: {result.Message}";
+                }
+
+                MessageBox.Show(this, body, "Purge Complete",
+                    MessageBoxButton.OK,
+                    string.Equals(result.Status, "SUCCESS", StringComparison.Ordinal)
+                        ? MessageBoxImage.Information
+                        : MessageBoxImage.Warning);
+            }
+            catch (Exception ex)
+            {
+                MessageBox.Show(this,
+                    $"Failed to run purge on '{server.DisplayNameWithIntent}':\n\n{ex.Message}",
+                    "Purge Failed",
+                    MessageBoxButton.OK,
+                    MessageBoxImage.Error);
+            }
+            finally
+            {
+                Cursor = null;
+            }
+        }
+
         private void CopyCell_Click(object sender, RoutedEventArgs e)
         {
             if (sender is MenuItem menuItem && menuItem.Parent is ContextMenu contextMenu)
diff --git a/Dashboard/PurgeNowDialog.xaml b/Dashboard/PurgeNowDialog.xaml
new file mode 100644
index 00000000..29f23cbc
--- /dev/null
+++ b/Dashboard/PurgeNowDialog.xaml
@@ -0,0 +1,53 @@
+<Window x:Class="PerformanceMonitorDashboard.PurgeNowDialog"
+        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
+        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+        Title="Purge Now"
+        Height="320" Width="500"
+        WindowStartupLocation="CenterOwner"
+        ResizeMode="NoResize"
+        Background="{DynamicResource BackgroundBrush}">
+    <Grid Margin="20">
+        <Grid.RowDefinitions>
+            <RowDefinition Height="Auto"/>
+            <RowDefinition Height="Auto"/>
+            <RowDefinition Height="Auto"/>
+            <RowDefinition Height="Auto"/>
+            <RowDefinition Height="*"/>
+            <RowDefinition Height="Auto"/>
+        </Grid.RowDefinitions>
+
+        <TextBlock Grid.Row="0" x:Name="HeaderText" TextWrapping="Wrap" FontSize="13" FontWeight="Bold"
+                   Foreground="{DynamicResource ForegroundBrush}" Margin="0,0,0,12"/>
+
+        <TextBlock Grid.Row="1" Text="Purge mode:" Margin="0,0,0,4"
+                   Foreground="{DynamicResource ForegroundBrush}"/>
+
+        <ComboBox Grid.Row="2" x:Name="ModeComboBox" Height="28" Margin="0,0,0,12"
+                  SelectionChanged="ModeComboBox_SelectionChanged">
+            <ComboBoxItem Content="Use configured retention" IsSelected="True" Tag="configured"/>
+            <ComboBoxItem Content="1 day" Tag="1"/>
+            <ComboBoxItem Content="3 days" Tag="3"/>
+            <ComboBoxItem Content="7 days" Tag="7"/>
+            <ComboBoxItem Content="Custom..." Tag="custom"/>
+            <ComboBoxItem x:Name="AllItem" Content="All — TRUNCATE everything" Tag="all"
+                          Foreground="{DynamicResource ErrorBrush}"/>
+        </ComboBox>
+
+        <StackPanel Grid.Row="3" x:Name="CustomDaysPanel" Orientation="Horizontal" Margin="0,0,0,12"
+                    Visibility="Collapsed">
+            <TextBlock Text="Retention (days):" VerticalAlignment="Center" Margin="0,0,8,0"
+                       Foreground="{DynamicResource ForegroundBrush}"/>
+            <TextBox x:Name="CustomDaysBox" Width="80" Height="26" Padding="6,0,6,0"
+                     VerticalContentAlignment="Center"
+                     Text="14" PreviewTextInput="CustomDaysBox_PreviewTextInput"/>
+        </StackPanel>
+
+        <TextBlock Grid.Row="4" x:Name="WarningText" TextWrapping="Wrap" FontSize="11"
+                   Foreground="{DynamicResource ErrorBrush}" Margin="0,4,0,8"/>
+
+        <StackPanel Grid.Row="5" Orientation="Horizontal" HorizontalAlignment="Right">
+            <Button x:Name="PurgeButton" Content="Purge" Width="80" Height="28" Margin="0,0,8,0" Click="Purge_Click"/>
+            <Button Content="Cancel" Width="80" Height="28" Click="Cancel_Click" IsCancel="True"/>
+        </StackPanel>
+    </Grid>
+</Window>
diff --git a/Dashboard/PurgeNowDialog.xaml.cs b/Dashboard/PurgeNowDialog.xaml.cs
new file mode 100644
index 00000000..c3b5a549
--- /dev/null
+++ b/Dashboard/PurgeNowDialog.xaml.cs
@@ -0,0 +1,114 @@
+/*
+ * Copyright (c) 2026 Erik Darling, Darling Data LLC
+ *
+ * This file is part of the SQL Server Performance Monitor.
+ *
+ * Licensed under the MIT License. See LICENSE file in the project root for full license information.
+ */
+
+using System.Text.RegularExpressions;
+using System.Windows;
+using System.Windows.Controls;
+using System.Windows.Input;
+
+namespace PerformanceMonitorDashboard
+{
+    public partial class PurgeNowDialog : Window
+    {
+        private readonly string _serverDisplayName;
+
+        /// <summary>
+        /// null = use configured retention.
+        /// 0 = TRUNCATE every collect.* table.
+        /// N > 0 = override every table's cutoff to N days.
+        /// </summary>
+        public int? RetentionDaysOverride { get; private set; }
+
+        public PurgeNowDialog(string serverDisplayName)
+        {
+            InitializeComponent();
+            _serverDisplayName = serverDisplayName;
+            HeaderText.Text = $"Purge collected data on '{serverDisplayName}'.";
+            UpdateWarningForMode("configured");
+        }
+
+        private void ModeComboBox_SelectionChanged(object sender, SelectionChangedEventArgs e)
+        {
+            /* Fires once during InitializeComponent before other named elements exist; bail until window is loaded. */
+            if (CustomDaysPanel is null || WarningText is null) return;
+
+            if (ModeComboBox.SelectedItem is not ComboBoxItem item) return;
+
+            string tag = item.Tag as string ?? "configured";
+            CustomDaysPanel.Visibility = tag == "custom" ? Visibility.Visible : Visibility.Collapsed;
+            UpdateWarningForMode(tag);
+        }
+
+        private void UpdateWarningForMode(string tag)
+        {
+            WarningText.Text = tag switch
+            {
+                "configured" => "Deletes data older than the per-collector retention configured in config.collection_schedule. Cannot be undone.",
+                "all"        => "WARNING: TRUNCATEs every collect.* table. Wipes ALL collected monitoring data on this server. Cannot be undone.",
+                "custom"     => "Deletes data older than the specified number of days. Cannot be undone.",
+                _            => $"Deletes data older than {tag} day(s). Cannot be undone."
+            };
+        }
+
+        private void CustomDaysBox_PreviewTextInput(object sender, TextCompositionEventArgs e)
+        {
+            e.Handled = !Regex.IsMatch(e.Text, "^[0-9]+$");
+        }
+
+        private void Purge_Click(object sender, RoutedEventArgs e)
+        {
+            if (ModeComboBox.SelectedItem is not ComboBoxItem item) return;
+
+            string tag = item.Tag as string ?? "configured";
+
+            switch (tag)
+            {
+                case "configured":
+                    RetentionDaysOverride = null;
+                    break;
+
+                case "1":
+                case "3":
+                case "7":
+                    RetentionDaysOverride = int.Parse(tag);
+                    break;
+
+                case "custom":
+                    if (!int.TryParse(CustomDaysBox.Text, out int days) || days < 1)
+                    {
+                        MessageBox.Show(this,
+                            "Enter a whole number of days greater than 0.",
+                            "Invalid Retention",
+                            MessageBoxButton.OK,
+                            MessageBoxImage.Warning);
+                        return;
+                    }
+                    RetentionDaysOverride = days;
+                    break;
+
+                case "all":
+                    var confirm = MessageBox.Show(this,
+                        $"This will TRUNCATE every collect.* table on '{_serverDisplayName}', wiping all monitoring data.\n\nAre you absolutely sure?",
+                        "Confirm Purge All",
+                        MessageBoxButton.YesNo,
+                        MessageBoxImage.Warning,
+                        MessageBoxResult.No);
+                    if (confirm != MessageBoxResult.Yes) return;
+                    RetentionDaysOverride = 0;
+                    break;
+            }
+
+            DialogResult = true;
+        }
+
+        private void Cancel_Click(object sender, RoutedEventArgs e)
+        {
+            DialogResult = false;
+        }
+    }
+}
diff --git a/Dashboard/Services/ServerManager.cs b/Dashboard/Services/ServerManager.cs
index d3686645..29ce934f 100644
--- a/Dashboard/Services/ServerManager.cs
+++ b/Dashboard/Services/ServerManager.cs
@@ -196,6 +196,94 @@ IF DB_ID('PerformanceMonitor') IS NOT NULL
             Logger.Info($"Dropped PerformanceMonitor database and Agent jobs on '{server.DisplayName}'");
         }
 
+        public class PurgeResult
+        {
+            public int RowsDeleted { get; set; }
+            public int TableCount { get; set; }
+            public int DurationMs { get; set; }
+            public string Status { get; set; } = "";
+            public string? Message { get; set; }
+        }
+
+        /// <summary>
+        /// Runs config.data_retention against the PerformanceMonitor database on the given server.
+        /// </summary>
+        /// <param name="retentionDaysOverride">
+        /// null = use per-collector retention from config.collection_schedule.
+        /// 0 = TRUNCATE every collect.* table.
+        /// N > 0 = override every table's cutoff to N days.
+        /// </param>
+        public async Task<PurgeResult> RunDataRetentionAsync(
+            ServerConnection server,
+            int? retentionDaysOverride)
+        {
+            var connectionString = server.GetConnectionString(_credentialService);
+            var builder = new SqlConnectionStringBuilder(connectionString)
+            {
+                InitialCatalog = "PerformanceMonitor",
+                ConnectTimeout = 10
+            };
+
+            using var connection = new SqlConnection(builder.ConnectionString);
+            await connection.OpenAsync();
+
+            using (var cmd = new SqlCommand("config.data_retention", connection))
+            {
+                cmd.CommandType = System.Data.CommandType.StoredProcedure;
+                cmd.CommandTimeout = 600;
+
+                if (retentionDaysOverride.HasValue)
+                {
+                    cmd.Parameters.Add(new SqlParameter("@retention_days", System.Data.SqlDbType.Int) { Value = retentionDaysOverride.Value });
+                }
+
+                await cmd.ExecuteNonQueryAsync();
+            }
+
+            using var readCmd = new SqlCommand(@"
+SELECT TOP (1)
+    cl.collection_status,
+    cl.rows_collected,
+    cl.duration_ms,
+    cl.error_message
+FROM config.collection_log AS cl
+WHERE cl.collector_name = N'data_retention'
+ORDER BY cl.collection_time DESC;", connection);
+            readCmd.CommandTimeout = 30;
+
+            using var reader = await readCmd.ExecuteReaderAsync();
+            var result = new PurgeResult();
+
+            if (await reader.ReadAsync())
+            {
+                result.Status = reader.IsDBNull(0) ? "" : reader.GetString(0);
+                result.RowsDeleted = reader.IsDBNull(1) ? 0 : reader.GetInt32(1);
+                result.DurationMs = reader.IsDBNull(2) ? 0 : reader.GetInt32(2);
+                result.Message = reader.IsDBNull(3) ? null : reader.GetString(3);
+
+                if (result.Message is not null && result.Message.StartsWith("Cleaned ", StringComparison.Ordinal))
+                {
+                    int spaceIdx = result.Message.IndexOf(' ', 8);
+                    if (spaceIdx > 8 && int.TryParse(result.Message.AsSpan(8, spaceIdx - 8), out int tableCount))
+                    {
+                        result.TableCount = tableCount;
+                    }
+                }
+                else if (result.Message is not null && result.Message.StartsWith("TRUNCATE all: ", StringComparison.Ordinal))
+                {
+                    int spaceIdx = result.Message.IndexOf(' ', 14);
+                    if (spaceIdx > 14 && int.TryParse(result.Message.AsSpan(14, spaceIdx - 14), out int tableCount))
+                    {
+                        result.TableCount = tableCount;
+                    }
+                }
+            }
+
+            Logger.Info($"Ran data_retention on '{server.DisplayName}': status={result.Status}, rowsDeleted={result.RowsDeleted}, tables={result.TableCount}, durationMs={result.DurationMs}");
+
+            return result;
+        }
+
         public void UpdateLastConnected(string id)
         {
             lock (_serversLock)
diff --git a/install/43_data_retention.sql b/install/43_data_retention.sql
index 09fa8666..96749569 100644
--- a/install/43_data_retention.sql
+++ b/install/43_data_retention.sql
@@ -35,7 +35,7 @@ GO
 ALTER PROCEDURE
     config.data_retention
 (
-    @retention_days integer = 30, /*Fallback retention for tables without a collection_schedule entry*/
+    @retention_days integer = NULL, /*NULL = use per-collector retention from config.collection_schedule (30-day fallback). 0 = TRUNCATE every collect.* table. N > 0 = override every table's cutoff to N days.*/
     @batch_size integer = 10000, /*Number of rows to delete per batch to avoid blocking*/
     @debug bit = 0 /*Print debugging information*/
 )
@@ -45,8 +45,16 @@ BEGIN
     SET NOCOUNT ON;
     SET TRANSACTION ISOLATION LEVEL READ UNCOMMITTED;
 
+    /*
+    NULL @retention_days means "respect per-collector schedule" with a 30-day fallback for unscheduled tables.
+    Non-NULL means "use this value as the cutoff everywhere" — schedule overrides are skipped.
+    */
     DECLARE
-        @retention_date datetime2(7) = DATEADD(DAY, -@retention_days, SYSDATETIME()),
+        @apply_schedule_override bit = CASE WHEN @retention_days IS NULL THEN 1 ELSE 0 END,
+        @effective_retention_days integer = ISNULL(@retention_days, 30);
+
+    DECLARE
+        @retention_date datetime2(7) = DATEADD(DAY, -@effective_retention_days, SYSDATETIME()),
         @total_deleted bigint = 0,
         @start_time datetime2(7) = SYSDATETIME(),
         @table_name sysname,
@@ -60,9 +68,9 @@ BEGIN
         /*
         Parameter validation
         */
-        IF @retention_days < 1
+        IF @retention_days IS NOT NULL AND @retention_days < 0
         BEGIN
-            RAISERROR(N'@retention_days must be at least 1', 16, 1);
+            RAISERROR(N'@retention_days must be 0 or greater', 16, 1);
             RETURN;
         END;
 
@@ -72,6 +80,130 @@ BEGIN
             RETURN;
         END;
 
+        /*
+        Purge-all branch: TRUNCATE every collect.* table when @retention_days = 0.
+        No FKs, schema-bound views, or indexed views reference collect.* so this is safe.
+        Config tables (including config.collection_log) are intentionally left alone.
+        */
+        IF @retention_days = 0
+        BEGIN
+            IF @debug = 1
+            BEGIN
+                RAISERROR(N'Starting purge-all: TRUNCATE every collect.* table', 0, 1) WITH NOWAIT;
+            END;
+
+            DECLARE
+                @truncate_table_name sysname,
+                @truncate_sql nvarchar(max),
+                @truncate_table_count integer = 0,
+                @truncate_error_count integer = 0,
+                @truncate_rows_before bigint = 0,
+                @truncate_cursor cursor;
+
+            /*
+            Snapshot total row count across collect.* before truncating so we can report
+            how many rows the user actually wiped. TRUNCATE doesn't return a count.
+            */
+            SELECT
+                @truncate_rows_before = ISNULL(SUM(p.rows), 0)
+            FROM sys.tables AS t
+            JOIN sys.schemas AS s
+              ON s.schema_id = t.schema_id
+            JOIN sys.partitions AS p
+              ON p.object_id = t.object_id
+              AND p.index_id IN (0, 1)
+            WHERE s.name = N'collect'
+            AND   t.is_ms_shipped = 0;
+
+            SET @truncate_cursor = CURSOR LOCAL FAST_FORWARD FOR
+                SELECT
+                    t.name
+                FROM sys.tables AS t
+                JOIN sys.schemas AS s
+                  ON s.schema_id = t.schema_id
+                WHERE s.name = N'collect'
+                AND   t.is_ms_shipped = 0
+                ORDER BY
+                    t.name;
+
+            OPEN @truncate_cursor;
+            FETCH NEXT FROM @truncate_cursor INTO @truncate_table_name;
+
+            WHILE @@FETCH_STATUS = 0
+            BEGIN
+                BEGIN TRY
+                    SET @truncate_sql = N'TRUNCATE TABLE collect.' + QUOTENAME(@truncate_table_name) + N';';
+
+                    IF @debug = 1
+                    BEGIN
+                        RAISERROR(N'  %s', 0, 1, @truncate_sql) WITH NOWAIT;
+                    END;
+
+                    EXECUTE sys.sp_executesql @truncate_sql;
+                    SET @truncate_table_count = @truncate_table_count + 1;
+                END TRY
+                BEGIN CATCH
+                    SET @truncate_error_count = @truncate_error_count + 1;
+                    SET @message = N'TRUNCATE failed for collect.' + QUOTENAME(@truncate_table_name) + N': ' + ERROR_MESSAGE();
+
+                    IF @debug = 1
+                    BEGIN
+                        RAISERROR(@message, 0, 1) WITH NOWAIT;
+                    END;
+
+                    INSERT INTO
+                        config.collection_log
+                    (
+                        collector_name,
+                        collection_status,
+                        error_message
+                    )
+                    VALUES
+                    (
+                        N'data_retention',
+                        N'ERROR',
+                        @message
+                    );
+                END CATCH;
+
+                FETCH NEXT FROM @truncate_cursor INTO @truncate_table_name;
+            END;
+
+            CLOSE @truncate_cursor;
+
+            INSERT INTO
+                config.collection_log
+            (
+                collector_name,
+                collection_status,
+                rows_collected,
+                duration_ms,
+                error_message
+            )
+            VALUES
+            (
+                N'data_retention',
+                CASE WHEN @truncate_error_count = 0 THEN N'SUCCESS' ELSE N'WARNING' END,
+                /*rows_collected is INT; clamp the bigint snapshot to int range*/
+                CONVERT(integer, CASE WHEN @truncate_rows_before > 2147483647 THEN 2147483647 ELSE @truncate_rows_before END),
+                DATEDIFF(MILLISECOND, @start_time, SYSDATETIME()),
+                N'TRUNCATE all: ' + CONVERT(nvarchar(10), @truncate_table_count) + N' tables truncated, '
+                + CONVERT(nvarchar(20), @truncate_rows_before) + N' rows wiped'
+                + CASE WHEN @truncate_error_count > 0
+                       THEN N', ' + CONVERT(nvarchar(10), @truncate_error_count) + N' errors'
+                       ELSE N''
+                  END
+            );
+
+            IF @debug = 1
+            BEGIN
+                RAISERROR(N'Purge-all completed: %d tables truncated, %I64d rows wiped, %d errors', 0, 1,
+                    @truncate_table_count, @truncate_rows_before, @truncate_error_count) WITH NOWAIT;
+            END;
+
+            RETURN;
+        END;
+
         IF @debug = 1
         BEGIN
             DECLARE @retention_date_string nvarchar(30) = CONVERT(nvarchar(30), @retention_date, 120);
@@ -247,42 +379,48 @@ BEGIN
 
         /*
         Override retention_date per-collector from config.collection_schedule.
-        Direct match: strip _collector/_analyzer suffix and match table name prefix.
+        Skipped when @retention_days was supplied — caller wants a flat cutoff across every table.
         */
-        UPDATE ttc
-        SET ttc.retention_date = DATEADD(DAY, -cs.retention_days, SYSDATETIME())
-        FROM #tables_to_clean AS ttc
-        JOIN config.collection_schedule AS cs
-          ON ttc.table_name LIKE REPLACE(REPLACE(cs.collector_name, N'_collector', N''), N'_analyzer', N'') + N'%';
+        IF @apply_schedule_override = 1
+        BEGIN
+            /*
+            Direct match: strip _collector/_analyzer suffix and match table name prefix.
+            */
+            UPDATE ttc
+            SET ttc.retention_date = DATEADD(DAY, -cs.retention_days, SYSDATETIME())
+            FROM #tables_to_clean AS ttc
+            JOIN config.collection_schedule AS cs
+              ON ttc.table_name LIKE REPLACE(REPLACE(cs.collector_name, N'_collector', N''), N'_analyzer', N'') + N'%';
 
-        /*
-        Special mappings for tables whose names don't match their collector:
-        - HealthParser_* tables -> system_health_collector
-        - blocking_BlockedProcessReport -> process_blocked_process_xml
-        - deadlocks (sp_BlitzLock output) -> process_deadlock_xml
-        */
-        UPDATE ttc
-        SET ttc.retention_date = DATEADD(DAY, -cs.retention_days, SYSDATETIME())
-        FROM #tables_to_clean AS ttc
-        CROSS JOIN config.collection_schedule AS cs
-        WHERE
-        (
-            ttc.table_name LIKE N'HealthParser%'
-            AND cs.collector_name = N'system_health_collector'
-        )
-        OR
-        (
-            ttc.table_name = N'blocking_BlockedProcessReport'
-            AND cs.collector_name = N'process_blocked_process_xml'
-        )
-        OR
-        (
-            ttc.table_name = N'deadlocks'
-            AND cs.collector_name = N'process_deadlock_xml'
-        );
+            /*
+            Special mappings for tables whose names don't match their collector:
+            - HealthParser_* tables -> system_health_collector
+            - blocking_BlockedProcessReport -> process_blocked_process_xml
+            - deadlocks (sp_BlitzLock output) -> process_deadlock_xml
+            */
+            UPDATE ttc
+            SET ttc.retention_date = DATEADD(DAY, -cs.retention_days, SYSDATETIME())
+            FROM #tables_to_clean AS ttc
+            CROSS JOIN config.collection_schedule AS cs
+            WHERE
+            (
+                ttc.table_name LIKE N'HealthParser%'
+                AND cs.collector_name = N'system_health_collector'
+            )
+            OR
+            (
+                ttc.table_name = N'blocking_BlockedProcessReport'
+                AND cs.collector_name = N'process_blocked_process_xml'
+            )
+            OR
+            (
+                ttc.table_name = N'deadlocks'
+                AND cs.collector_name = N'process_deadlock_xml'
+            );
+        END;
 
         /*
-        Special handling for config.collection_log - keep 2x longer
+        Special handling for config.collection_log - keep 2x longer than the effective retention
         */
         INSERT INTO
             #tables_to_clean
@@ -296,7 +434,7 @@ BEGIN
             schema_name = N'config',
             table_name = N'collection_log',
             time_column_name = N'collection_time',
-            retention_date = DATEADD(DAY, -(@retention_days * 2), SYSDATETIME())
+            retention_date = DATEADD(DAY, -(@effective_retention_days * 2), SYSDATETIME())
         WHERE EXISTS
         (
             SELECT
@@ -486,13 +624,19 @@ GO
 
 PRINT 'Data retention procedure created successfully (DYNAMIC VERSION)';
 PRINT 'Use config.data_retention to automatically purge old monitoring data';
-PRINT 'Uses per-collector retention from config.collection_schedule when available';
-PRINT 'Falls back to @retention_days parameter for unmatched tables';
+PRINT '';
+PRINT '  @retention_days = NULL (default): respect per-collector retention in config.collection_schedule';
+PRINT '                                    (30-day fallback for unscheduled tables)';
+PRINT '  @retention_days = 0            : TRUNCATE every collect.* table';
+PRINT '  @retention_days = N (N > 0)    : override every table''s cutoff to N days';
 PRINT '';
 PRINT 'Examples:';
 PRINT '  -- Use per-collector retention (default)';
 PRINT '  EXECUTE config.data_retention @debug = 1;';
 PRINT '';
-PRINT '  -- Override fallback to 90 days for tables without schedule entries';
-PRINT '  EXECUTE config.data_retention @retention_days = 90;';
+PRINT '  -- Override every table to 7-day retention';
+PRINT '  EXECUTE config.data_retention @retention_days = 7;';
+PRINT '';
+PRINT '  -- Purge all collected data (TRUNCATE every collect.* table)';
+PRINT '  EXECUTE config.data_retention @retention_days = 0;';
 GO