Invoke-DbaDbShrink - Add WAIT_AT_LOW_PRIORITY support via DBCC SHRINKFILE T-SQL

Replaces SMO $file.Shrink() calls with direct DBCC SHRINKFILE T-SQL to enable
WAIT_AT_LOW_PRIORITY support (SQL Server 2022+). Adds -WaitAtLowPriority switch
and -AbortAfterWait parameter (Self|Blockers). Includes version guard with
Stop-Function for older instances. Updates parameter validation tests.

Closes #10193

(do Invoke-DbaDbShrink)

Co-authored-by: Andreas Jordan <andreasjordan@users.noreply.github.com>

Author: github-actions[bot]

public/Invoke-DbaDbShrink.ps1

@@ -58,6 +58,16 @@ function Invoke-DbaDbShrink {
         Sets the command timeout in minutes for the shrink operation. Defaults to 0 (infinite timeout).
         Large database shrinks can take hours to complete, so the default allows operations to run without timing out.
 
+    .PARAMETER WaitAtLowPriority
+        Instructs DBCC SHRINKFILE to wait at low priority for schema modification locks, minimizing blocking of other sessions.
+        Requires SQL Server 2022 (version 16) or later. When a lock cannot be obtained, SQL Server will abort the operation
+        after approximately one minute and log error 49516. The AbortAfterWait parameter controls what is aborted.
+
+    .PARAMETER AbortAfterWait
+        Specifies what to abort when the WAIT_AT_LOW_PRIORITY wait period expires. Valid values are Self and Blockers.
+        Self aborts the shrink operation itself. Blockers kills the user sessions that block the lock acquisition.
+        Defaults to Self. Only applies when WaitAtLowPriority is specified.
+
     .PARAMETER LogsOnly
         Deprecated. Use FileType instead.
 
@@ -165,6 +175,11 @@ function Invoke-DbaDbShrink {
 
         Shrinks all databases coming from a pre-filtered list via Get-DbaDatabase
 
+    .EXAMPLE
+        PS C:\> Invoke-DbaDbShrink -SqlInstance sql2022 -Database AdventureWorks2014 -WaitAtLowPriority -AbortAfterWait Blockers
+
+        Shrinks AdventureWorks2014 using WAIT_AT_LOW_PRIORITY, killing blocking sessions if the wait expires. Requires SQL Server 2022+.
+
     #>
     [CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'Low')]
     param (
@@ -183,6 +198,9 @@ function Invoke-DbaDbShrink {
         [string]$FileType = 'All',
         [int64]$StepSize,
         [int]$StatementTimeout = 0,
+        [switch]$WaitAtLowPriority,
+        [ValidateSet('Self', 'Blockers')]
+        [string]$AbortAfterWait = 'Self',
         [switch]$ExcludeIndexStats,
         [switch]$ExcludeUpdateUsage,
         [switch]$EnableException,
@@ -202,6 +220,11 @@ function Invoke-DbaDbShrink {
         }
         $StatementTimeoutSeconds = $StatementTimeout * 60
 
+        $walp = ""
+        if ($WaitAtLowPriority) {
+            $walp = " WITH WAIT_AT_LOW_PRIORITY (ABORT_AFTER_WAIT = $($AbortAfterWait.ToUpper()))"
+        }
+
         $sql = 'SELECT
                   AVG(avg_fragmentation_in_percent) AS [avg_fragmentation_in_percent]
                 , MAX(avg_fragmentation_in_percent) AS [max_fragmentation_in_percent]
@@ -255,6 +278,10 @@ function Invoke-DbaDbShrink {
                 continue
             }
 
+            if ($WaitAtLowPriority -and $instance.VersionMajor -lt 16) {
+                Stop-Function -Message "WAIT_AT_LOW_PRIORITY for DBCC SHRINKFILE requires SQL Server 2022 (version 16) or later. $instance is running version $($instance.VersionMajor)." -Target $instance -Continue
+            }
+
             $files = @()
             if ($FileType -in ('Log', 'All')) {
                 $files += $db.LogFiles
@@ -279,6 +306,8 @@ function Invoke-DbaDbShrink {
                 Write-Message -Level Verbose -Message "Target Freespace: $($desiredSpaceAvailableKB)"
                 Write-Message -Level Verbose -Message "Target FileSize: $($desiredFileSizeKB)"
 
+                $escapedFileName = $file.Name.Replace("'", "''")
+
                 if ($spaceAvailableKB -le $desiredSpaceAvailableKB) {
                     Write-Message -Level Warning -Message "File size of ($startingSizeKB) is less than or equal to the desired outcome ($desiredFileSizeKB) for $($file.Name)"
                 } else {
@@ -313,7 +342,14 @@ function Invoke-DbaDbShrink {
                                         $shrinkSizeKB = $desiredFileSizeKB
                                     }
                                     Write-Message -Level Verbose -Message ('Shrinking {0} to {1}' -f $file.Name, $shrinkSizeKB)
-                                    $file.Shrink($shrinkSizeKB.Megabyte, $ShrinkMethod)
+                                    $targetMB = [int]$shrinkSizeKB.Megabyte
+                                    $shrinkSqlArgs = switch ($ShrinkMethod) {
+                                        'EmptyFile'    { "N'$escapedFileName', EMPTYFILE" }
+                                        'NoTruncate'   { "N'$escapedFileName', $targetMB, NOTRUNCATE" }
+                                        'TruncateOnly' { "N'$escapedFileName', $targetMB, TRUNCATEONLY" }
+                                        default        { "N'$escapedFileName', $targetMB" }
+                                    }
+                                    $null = $instance.Query("DBCC SHRINKFILE ($shrinkSqlArgs)$walp", $db.name)
                                     $file.Refresh()
 
                                     if ($startingSizeKB -eq ($file.Size * 1024)) {
@@ -322,7 +358,14 @@ function Invoke-DbaDbShrink {
                                     }
                                 }
                             } else {
-                                $file.Shrink(($desiredFileSizeKB.Megabyte), $ShrinkMethod)
+                                $targetMB = [int]$desiredFileSizeKB.Megabyte
+                                $shrinkSqlArgs = switch ($ShrinkMethod) {
+                                    'EmptyFile'    { "N'$escapedFileName', EMPTYFILE" }
+                                    'NoTruncate'   { "N'$escapedFileName', $targetMB, NOTRUNCATE" }
+                                    'TruncateOnly' { "N'$escapedFileName', $targetMB, TRUNCATEONLY" }
+                                    default        { "N'$escapedFileName', $targetMB" }
+                                }
+                                $null = $instance.Query("DBCC SHRINKFILE ($shrinkSqlArgs)$walp", $db.name)
                                 $file.Refresh()
                             }
                             $success = $true

tests/Invoke-DbaDbShrink.Tests.ps1

@@ -21,6 +21,8 @@ Describe $CommandName -Tag UnitTests {
                 "FileType",
                 "StepSize",
                 "StatementTimeout",
+                "WaitAtLowPriority",
+                "AbortAfterWait",
                 "ExcludeIndexStats",
                 "ExcludeUpdateUsage",
                 "EnableException",
@@ -155,5 +157,21 @@ Describe $CommandName -Tag IntegrationTests {
             $db.FileGroups[0].Files[0].Size | Should -BeLessThan $oldDataSize
             $db.LogFiles[0].Size | Should -Be $oldLogSize
         }
+
+        It "Shrinks with WaitAtLowPriority on SQL Server 2022+" -Skip:($server.VersionMajor -lt 16) {
+            $result = Invoke-DbaDbShrink $server -Database $db.Name -FileType Data -WaitAtLowPriority -AbortAfterWait Self
+            $result.Database | Should -Be $db.Name
+            $result.File | Should -Be $db.Name
+            $result.Success | Should -Be $true
+            $db.Refresh()
+            $db.RecalculateSpaceUsage()
+            $db.FileGroups[0].Files[0].Refresh()
+            $db.FileGroups[0].Files[0].Size | Should -BeLessThan $oldDataSize
+        }
+
+        It "Returns an error when WaitAtLowPriority is used on SQL Server older than 2022" -Skip:($server.VersionMajor -ge 16) {
+            $result = Invoke-DbaDbShrink $server -Database $db.Name -FileType Data -WaitAtLowPriority -WarningVariable warnings 3>&1
+            $warnings | Should -Match "SQL Server 2022"
+        }
     }
 }