Invoke-DbaDbLogShipping - Add Azure blob storage support

.github/scripts/gh-actions.ps1

@@ -272,6 +272,146 @@ exec sp_addrolemember 'userrole','bob';
         (Get-DbaDatabase -SqlInstance $server -Database test).Name | Should -Be "test"
     }
 
+    It -Skip:(-not $env:azurepasswd) "sets up log shipping to Azure blob storage using SAS token" {
+        # Restore credentials after Azure tests cleared PSDefaultParameterValues
+        $password = ConvertTo-SecureString "dbatools.IO" -AsPlainText -Force
+        $cred = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList "sqladmin", $password
+
+        $azureUrl = "https://dbatools.blob.core.windows.net/dbatools"
+        $dbName = "dbatoolsci_logship_azure"
+
+        # Create SAS token credential on both instances
+        $primaryServer = Connect-DbaInstance -SqlInstance localhost -SqlCredential $cred
+        if (Get-DbaCredential -SqlInstance localhost -SqlCredential $cred -Name "[$azureUrl]") {
+            $primaryServer.Query("DROP CREDENTIAL [$azureUrl]")
+        }
+        # Strip leading ? from SAS token if present
+        $sasToken = $env:azurepasswd.TrimStart("?")
+        $sql = "CREATE CREDENTIAL [$azureUrl] WITH IDENTITY = N'SHARED ACCESS SIGNATURE', SECRET = N'$sasToken'"
+        $primaryServer.Query($sql)
+
+        $secondaryServer = Connect-DbaInstance -SqlInstance localhost:14333 -SqlCredential $cred
+        if (Get-DbaCredential -SqlInstance localhost:14333 -SqlCredential $cred -Name "[$azureUrl]") {
+            $secondaryServer.Query("DROP CREDENTIAL [$azureUrl]")
+        }
+        $secondaryServer.Query($sql)
+
+        # Create test database
+        $null = New-DbaDatabase -SqlInstance localhost -SqlCredential $cred -Name $dbName
+
+        # Set up log shipping
+        $splatLogShipping = @{
+            SourceSqlInstance        = "localhost"
+            SourceSqlCredential      = $cred
+            DestinationSqlInstance   = "localhost:14333"
+            DestinationSqlCredential = $cred
+            Database                 = $dbName
+            AzureBaseUrl             = $azureUrl
+            GenerateFullBackup       = $true
+            Force                    = $true
+        }
+        $Error.Clear()
+        $results = Invoke-DbaDbLogShipping @splatLogShipping
+
+        # If failed, output detailed error information for debugging
+        if ($results.Result -ne "Success") {
+            Write-Host "=== Log Shipping Failed ==="
+            Write-Host "Results object:"
+            $results | Format-List * | Out-String | Write-Host
+            Write-Host "`nError details:"
+            $Error | Select-Object -First 5 | ForEach-Object {
+                Write-Host "---"
+                Write-Host "Exception: $($_.Exception.Message)"
+                Write-Host "Category: $($_.CategoryInfo.Category)"
+                Write-Host "TargetObject: $($_.TargetObject)"
+                if ($_.Exception.InnerException) {
+                    Write-Host "InnerException: $($_.Exception.InnerException.Message)"
+                }
+            }
+            Write-Host "==========================="
+        }
+
+        $results.Result | Should -Be "Success"
+
+        # Verify backup job created
+        $jobs = Get-DbaAgentJob -SqlInstance localhost -SqlCredential $cred
+        $backupJob = $jobs | Where-Object Name -like "*LSBackup*$dbName*"
+        $backupJob | Should -Not -BeNullOrEmpty
+
+        # Verify restore job created
+        $jobs = Get-DbaAgentJob -SqlInstance localhost:14333 -SqlCredential $cred
+        $restoreJob = $jobs | Where-Object Name -like "*LSRestore*$dbName*"
+        $restoreJob | Should -Not -BeNullOrEmpty
+
+        # Verify NO copy job created (Azure optimization)
+        $copyJob = $jobs | Where-Object Name -like "*LSCopy*$dbName*"
+
+        # Debug: Show all jobs if copy job exists
+        if ($copyJob) {
+            Write-Host "=== COPY JOB STILL EXISTS ==="
+            Write-Host "All jobs on secondary:"
+            $jobs | Where-Object Name -like "*$dbName*" | ForEach-Object {
+                Write-Host "  - $($_.Name) (Enabled: $($_.IsEnabled))"
+            }
+            Write-Host "Copy job details:"
+            $copyJob | Format-List Name, IsEnabled, OwnerLoginName, DateCreated | Out-String | Write-Host
+            Write-Host "============================"
+        }
+
+        $copyJob | Should -BeNullOrEmpty
+
+        # Cleanup
+        $splatRemoveLogShipping = @{
+            PrimarySqlInstance     = "localhost"
+            PrimarySqlCredential   = $cred
+            SecondarySqlInstance   = "localhost:14333"
+            SecondarySqlCredential = $cred
+            Database               = $dbName
+            WarningAction          = "SilentlyContinue"
+        }
+        $null = Remove-DbaDbLogShipping @splatRemoveLogShipping
+        $null = Remove-DbaDatabase -SqlInstance localhost -SqlCredential $cred -Database $dbName -Confirm:$false
+        $null = Remove-DbaDatabase -SqlInstance localhost:14333 -SqlCredential $cred -Database $dbName -Confirm:$false
+        $primaryServer.Query("DROP CREDENTIAL [$azureUrl]")
+        $secondaryServer.Query("DROP CREDENTIAL [$azureUrl]")
+
+        # Clean up Azure blob storage test files
+        if ($env:azurepasswd) {
+            try {
+                $splatAzList = @(
+                    "storage", "blob", "list"
+                    "--account-name", "dbatools"
+                    "--container-name", "dbatools"
+                    "--prefix", $dbName
+                    "--sas-token", $sasToken
+                    "--query", "[].name"
+                    "--output", "tsv"
+                )
+                $blobs = & az @splatAzList 2>$null
+                if ($blobs) {
+                    $blobs -split "`n" | Where-Object { $_ } | ForEach-Object {
+                        $splatAzDelete = @(
+                            "storage", "blob", "delete"
+                            "--account-name", "dbatools"
+                            "--container-name", "dbatools"
+                            "--name", $_
+                            "--sas-token", $sasToken
+                            "--output", "none"
+                        )
+                        $null = & az @splatAzDelete 2>$null
+                    }
+                }
+            } catch {
+                # Ignore Azure cleanup errors - test may run in environments without Azure CLI
+            }
+        }
+    }
+
+    # Storage account key test removed - deprecated authentication method
+    # - Storage account keys create page blobs (limited to 1 TB, more expensive)
+    # - Microsoft recommends SAS tokens for SQL Server 2016+ (creates block blobs, up to 12.8 TB striped)
+    # - Use the SAS token test above for modern Azure blob storage log shipping
+
     It "tests Get-DbaLastGoodCheckDb against Azure" {
         $PSDefaultParameterValues.Clear()
         $securestring = ConvertTo-SecureString $env:CLIENTSECRET -AsPlainText -Force

.github/workflows/integration-tests.yml

@@ -99,6 +99,8 @@ jobs:
           CLIENTSECRET: ${{secrets.CLIENTSECRET}}
           CLIENT_GUID: ${{secrets.CLIENT_GUID}}
           CLIENT_GUID_SECRET: ${{secrets.CLIENT_GUID_SECRET}}
+          azurepasswd: ${{secrets.AZUREPASSWD}}
+          azurelegacypasswd: ${{secrets.AZURELEGACYPASSWD}}
         run: |
           Import-Module ./dbatools.psd1 -Force
           Get-DbatoolsConfigValue -FullName sql.connection.trustcert | Write-Warning

.gitignore

@@ -58,3 +58,4 @@ allcommands.ps1
 /.aitools
 .aider*
 /.shadowgit.git
+/.claude

CLAUDE.md

@@ -38,6 +38,8 @@ param(
 - Use `[Parameter(Mandatory)]` not `[Parameter(Mandatory = $true)]`
 - Use `[switch]` for boolean flags, not `[bool]` parameters
 - Keep non-boolean attributes with values: `[Parameter(ValueFromPipelineByPropertyName = "Name")]`
+- Avoid ParameterSets - their error messages are terrible and hard to use. Use Test-Bound instead and provide users with useful, concrete error messages.
+- No extra line breaks between parameter declarations - keep parameter blocks compact without blank lines separating individual parameters.
 
 ### POWERSHELL v3 COMPATIBILITY
 

private/functions/New-DbaLogShippingPrimaryDatabase.ps1

@@ -79,7 +79,7 @@ function New-DbaLogShippingPrimaryDatabase {
             It will also remove the any present schedules with the same name for the specific job.
 
         .NOTES
-            Author: Sander Stad (@sqlstad, sqlstad.nl)
+            Author: Sander Stad (@sqlstad, sqlstad.nl), Azure blob storage support added by Claude
             Website: https://dbatools.io
             Copyright: (c) 2018 by dbatools, licensed under MIT
             License: MIT https://opensource.org/licenses/MIT
@@ -117,6 +117,7 @@ function New-DbaLogShippingPrimaryDatabase {
         [object]$MonitorServerSecurityMode = 1,
         [System.Management.Automation.PSCredential]$MonitorCredential,
         [switch]$ThresholdAlertEnabled,
+        [string]$AzureCredential,
         [switch]$EnableException,
         [switch]$Force
     )
@@ -129,14 +130,63 @@ function New-DbaLogShippingPrimaryDatabase {
         return
     }
 
-    # Check if the backup UNC path is correct and reachable
-    if ([bool]([uri]$BackupShare).IsUnc -and $BackupShare -notmatch '^\\(?:\\[^<>:`"/\\|?*]+)+$') {
-        Stop-Function -Message "The backup share path $BackupShare should be formatted in the form \\server\share." -Target $SqlInstance
-        return
+    # Check if using Azure blob storage or traditional UNC path
+    $IsAzureUrl = $BackupShare -match '^https?://'
+
+    if ($IsAzureUrl) {
+        # Azure blob storage URL - validate format
+        Write-Message -Message "Using Azure blob storage for log shipping backups: $BackupShare" -Level Verbose
+
+        if ($BackupShare -notmatch '^https?://[a-z0-9]{3,24}\.blob\.core\.windows\.net/[a-z0-9]([a-z0-9\-]*[a-z0-9])?') {
+            Stop-Function -Message "The Azure backup URL $BackupShare should be in the format https://storageaccount.blob.core.windows.net/container (example: https://mystorageaccount.blob.core.windows.net/logshipping)" -Target $SqlInstance
+            return
+        }
+
+        # Check SQL Server version (Azure backup requires SQL Server 2012+)
+        if ($server.Version.Major -lt 11) {
+            Stop-Function -Message "Azure blob storage backup requires SQL Server 2012 or later. Instance is version $($server.Version.Major)" -Target $SqlInstance
+            return
+        }
+
+        # Validate Azure credential exists on SQL Server instance
+        # For storage account key authentication, use explicit credential name if provided
+        # For SAS token authentication, credential name must match the container URL
+        if ($AzureCredential) {
+            # Explicit credential name provided (storage account key authentication)
+            $credentialName = $AzureCredential
+            Write-Message -Message "Using explicit Azure credential name: $credentialName" -Level Verbose
+        } else {
+            # No explicit credential - assume SAS token (credential name must match URL)
+            # Extract base container URL from database-specific path if needed
+            $base = $BackupShare -split "/"
+            if ($base.Count -gt 4) {
+                # URL has subfolders (database-specific path), extract base container URL
+                $credentialName = $base[0] + "//" + $base[2] + "/" + $base[3]
+                Write-Message -Message "Extracted base credential name from database path: $credentialName" -Level Verbose
+            } else {
+                # URL is just the container
+                $credentialName = $BackupShare
+            }
+        }
+
+        $credential = $server.Credentials | Where-Object Name -eq $credentialName
+
+        if (-not $credential) {
+            Stop-Function -Message "Azure blob storage requires a SQL Server credential named '$credentialName' to exist on instance $SqlInstance. Create the credential using New-DbaCredential with either a Shared Access Signature (SAS) token or storage account key before setting up log shipping." -Target $SqlInstance
+            return
+        }
+
+        Write-Message -Message "Found Azure credential: $credentialName" -Level Verbose
     } else {
-        if (-not ((Test-DbaPath -Path $BackupShare -SqlInstance $server) -and ((Get-Item $BackupShare).PSProvider.Name -eq 'FileSystem'))) {
-            Stop-Function -Message "The backup share path $BackupShare is not valid or can't be reached." -Target $SqlInstance
+        # Traditional UNC path - validate format and accessibility
+        if ([bool]([uri]$BackupShare).IsUnc -and $BackupShare -notmatch '^\\(?:\\[^<>:`"/\\|?*]+)+$') {
+            Stop-Function -Message "The backup share path $BackupShare should be formatted in the form \\server\share." -Target $SqlInstance
             return
+        } else {
+            if (-not ((Test-DbaPath -Path $BackupShare -SqlInstance $server) -and ((Get-Item $BackupShare).PSProvider.Name -eq 'FileSystem'))) {
+                Stop-Function -Message "The backup share path $BackupShare is not valid or can't be reached." -Target $SqlInstance
+                return
+            }
         }
     }