Restore-DbaDatabase - Add -StopAtLsn parameter for LSN-based restore

Add -StopAtLsn parameter to Restore-DbaDatabase and Invoke-DbaAdvancedRestore
to support restoring to a specific Log Sequence Number using SQL Server's
STOPATMARK = 'lsn:<value>' syntax. Works with -StopBefore to stop just
before the specified LSN.

(do Restore-DbaDatabase)

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

Author: github-actions[bot]

public/Invoke-DbaAdvancedRestore.ps1

@@ -117,15 +117,20 @@ function Invoke-DbaAdvancedRestore {
         Provides more granular control than timestamp-based recovery for critical business operations.
 
     .PARAMETER StopBefore
-        Stops the restore operation just before the specified StopMark rather than after it.
-        Use this when you need to exclude a particular marked transaction from the restored database.
-        Only effective when used in combination with the StopMark parameter for mark-based recovery scenarios.
+        Stops the restore operation just before the specified StopMark or StopAtLsn rather than after it.
+        Use this when you need to exclude a particular marked transaction or LSN from the restored database.
+        Only effective when used in combination with the StopMark or StopAtLsn parameter.
 
     .PARAMETER StopAfterDate
         DateTime value specifying that only StopMark occurrences after this date should be considered for restore termination.
         Use this when the same mark name appears multiple times in your transaction log backups.
         Ensures the restore stops at the correct instance of the mark when identical mark names exist at different times.
 
+    .PARAMETER StopAtLsn
+        Log Sequence Number (LSN) in the transaction log at which to stop the restore operation.
+        Use this for precise point-in-time recovery to an exact LSN, which provides more granular control than timestamp-based recovery.
+        The LSN value can be obtained from sys.fn_dblog, backup headers, or error logs. Combine with -StopBefore to stop just before the specified LSN.
+
     .PARAMETER Checksum
         Enables backup checksum verification during restore operations. Forces the restore to verify backup checksums and fail if checksums are not present.
         Use this to ensure backup files contain checksums and validate them during restore, following backup best practices.
@@ -239,6 +244,7 @@ function Invoke-DbaAdvancedRestore {
         [switch]$StopBefore,
         [string]$StopMark,
         [datetime]$StopAfterDate,
+        [string]$StopAtLsn,
         [switch]$Checksum,
         [switch]$Restart,
         [switch]$EnableException
@@ -323,7 +329,13 @@ function Invoke-DbaAdvancedRestore {
                 } else {
                     $restore.NoRecovery = $False
                 }
-                if (-not [string]::IsNullOrEmpty($StopMark)) {
+                if (-not [string]::IsNullOrEmpty($StopAtLsn)) {
+                    if ($StopBefore -eq $True) {
+                        $restore.StopBeforeMarkName = "lsn:$StopAtLsn"
+                    } else {
+                        $restore.StopAtMarkName = "lsn:$StopAtLsn"
+                    }
+                } elseif (-not [string]::IsNullOrEmpty($StopMark)) {
                     if ($StopBefore -eq $True) {
                         $restore.StopBeforeMarkName = $StopMark
                         if ($null -ne $StopAfterDate) {

public/Restore-DbaDatabase.ps1

@@ -235,11 +235,16 @@ function Restore-DbaDatabase {
         Marked point in the transaction log to stop the restore at (Mark is created via BEGIN TRANSACTION (https://docs.microsoft.com/en-us/sql/t-sql/language-elements/begin-transaction-transact-sql?view=sql-server-ver15)).
 
     .PARAMETER StopBefore
-        Switch to indicate the restore should stop before StopMark occurs, default is to stop when mark is created.
+        Switch to indicate the restore should stop before StopMark or StopAtLsn occurs, default is to stop when mark/LSN is reached.
 
     .PARAMETER StopAfterDate
         By default the restore will stop at the first occurence of StopMark found in the chain, passing a datetime where will cause it to stop the first StopMark atfer that datetime.
 
+    .PARAMETER StopAtLsn
+        Log Sequence Number (LSN) in the transaction log at which to stop the restore operation.
+        Use this for precise point-in-time recovery to an exact LSN, which provides more granular control than timestamp-based recovery.
+        The LSN value can be obtained from sys.fn_dblog, backup headers, or error logs. Combine with -StopBefore to stop just before the specified LSN.
+
     .PARAMETER Checksum
         Enables backup checksum verification during restore operations. Forces the restore to verify backup checksums and fail if checksums are not present.
         Use this to ensure backup files contain checksums and validate them during restore, following backup best practices.
@@ -430,6 +435,16 @@ function Restore-DbaDatabase {
 
         Restores the backups from \\ServerName\ShareName\File as database, stops before the first 'OvernightStart' mark that occurs after '21:00 10/05/2020'.
 
+    .EXAMPLE
+        PS C:\> Restore-DbaDatabase -SqlInstance server1 -Path \\ServerName\ShareName\File -DatabaseName database -StopAtLsn '00000030:00000f28:0001'
+
+        Restores the backups from \\ServerName\ShareName\File as database, stopping when the specified LSN is reached.
+
+    .EXAMPLE
+        PS C:\> Restore-DbaDatabase -SqlInstance server1 -Path \\ServerName\ShareName\File -DatabaseName database -StopAtLsn '00000030:00000f28:0001' -StopBefore
+
+        Restores the backups from \\ServerName\ShareName\File as database, stopping just before the specified LSN is reached.
+
         Note that Date time needs to be specified in your local SQL Server culture
 
     .EXAMPLE
@@ -498,6 +513,7 @@ function Restore-DbaDatabase {
         [switch]$StopBefore,
         [string]$StopMark,
         [datetime]$StopAfterDate = (Get-Date '01/01/1971'),
+        [string]$StopAtLsn,
         [int]$StatementTimeout = 0,
         [parameter(ParameterSetName = "Restore")][parameter(ParameterSetName = "RestorePage")][switch]$Checksum,
         [parameter(ParameterSetName = "Restore")][parameter(ParameterSetName = "RestorePage")][switch]$Restart
@@ -891,6 +907,7 @@ function Restore-DbaDatabase {
                     StopMark          = $StopMark
                     StopAfterDate     = $StopAfterDate
                     StopBefore        = $StopBefore
+                    StopAtLsn         = $StopAtLsn
                     ExecuteAs         = $ExecuteAs
                     Checksum          = $Checksum
                     Restart           = $Restart