Start-DbaMigration: Enhance handling of dedicated admin connections (#10162)

Author: andreasjordan

.github/scripts/gh-actions.ps1

@@ -35,7 +35,7 @@ Describe "Integration Tests" -Tag "IntegrationTests" {
         $params = @{
             MasterKeyPassword = $cred.Password
             BackupRestore     = $true
-            Exclude           = "LinkedServers", "Credentials", "DataCollector", "EndPoints", "PolicyManagement", "ResourceGovernor", "BackupDevices"
+            Exclude           = "DatabaseMail", "LinkedServers", "Credentials", "DataCollector", "EndPoints", "PolicyManagement", "ResourceGovernor", "BackupDevices"
         }
         # something is up with docker on actions, adjust accordingly for the cert test
         $initialcertcount = (Get-DbaDbCertificate -SqlInstance localhost:14333 -Database master).Count

public/Start-DbaMigration.ps1

@@ -52,6 +52,11 @@ function Start-DbaMigration {
         Specifies credentials to connect to the destination SQL Server instance(s). Use when the current Windows account lacks sufficient permissions.
         Accepts PowerShell credential objects created with Get-Credential for SQL Authentication or alternative Windows accounts.
 
+    .PARAMETER Credential
+        Login to the target OS using alternative credentials. Accepts credential objects (Get-Credential)
+
+        Only used when passwords are being exported, as it requires access to the Windows OS via PowerShell remoting to decrypt the passwords.
+
     .PARAMETER BackupRestore
         Uses backup and restore method to migrate databases instead of detach/attach. Creates copy-only backups to preserve existing backup chains.
         Requires either -SharedPath for new backups or -UseLastBackup to restore from existing backup files.
@@ -152,6 +157,10 @@ function Start-DbaMigration {
         Required when migrating databases with encrypted objects or certificates that need master key protection.
         Must be provided as a SecureString object for security.
 
+    .PARAMETER ExcludePassword
+        Copies credentials, linked servers, and other objects without the actual password values.
+        Use this in security-conscious environments where password decryption is restricted or when passwords should be manually reset after migration.
+
     .PARAMETER Force
         Overwrites existing objects on the destination server without prompting for confirmation.
         For databases: drops existing databases with matching names before restoring.
@@ -242,6 +251,7 @@ function Start-DbaMigration {
     param (
         [DbaInstanceParameter]$Source,
         [DbaInstanceParameter[]]$Destination,
+        [PSCredential]$Credential,
         [switch]$DetachAttach,
         [switch]$Reattach,
         [switch]$BackupRestore,
@@ -264,6 +274,7 @@ function Start-DbaMigration {
         [switch]$KeepCDC,
         [switch]$KeepReplication,
         [switch]$Continue,
+        [switch]$ExcludePassword,
         [switch]$Force,
         [string]$AzureCredential,
         [Security.SecureString]$MasterKeyPassword,
@@ -348,7 +359,40 @@ function Start-DbaMigration {
         }
 
         try {
-            $sourceserver = Connect-DbaInstance -SqlInstance $Source -SqlCredential $SourceSqlCredential
+            # Do we need a dedicated admin connection to the source for password retrieval?
+            # If not all of the three are excluded, we do
+            $dacNeeded = $Exclude -notcontains 'Credentials' -or $Exclude -notcontains 'DatabaseMail' -or $Exclude -notcontains 'LinkedServers'
+            # If passwords are excluded, we don't need a DAC
+            if ($ExcludePassword) { $dacNeeded = $false }
+
+            # Do we have a dedicated admin connection already?
+            $dacConnected = $Source.Type -eq 'Server' -and $Source.InputObject.Name -match '^ADMIN:'
+
+            $dacOpened = $false
+            if ($dacNeeded) {
+                if ($dacConnected) {
+                    Write-Message -Level Verbose -Message "Reusing dedicated admin connection for password retrieval."
+                    $sourceServerDac = $Source.InputObject
+                    # Reconnect without DAC for Copy-DbaDatabase
+                    Write-Message -Level Verbose -Message "Opening additional normal connection for all commands that don't require DAC."
+                    $sourceServer = Connect-DbaInstance -SqlInstance $Source.FullName -SqlCredential $SourceSqlCredential
+                } else {
+                    Write-Message -Level Verbose -Message "Opening dedicated admin connection for password retrieval."
+                    $sourceServerDac = Connect-DbaInstance -SqlInstance $Source -SqlCredential $SourceSqlCredential -DedicatedAdminConnection -WarningAction SilentlyContinue
+                    $dacOpened = $true
+                    Write-Message -Level Verbose -Message "Opening or reusing additional normal connection for all commands that don't require DAC."
+                    $sourceServer = Connect-DbaInstance -SqlInstance $Source -SqlCredential $SourceSqlCredential
+                }
+            } else {
+                if ($dacConnected) {
+                    # Reconnect without DAC for Copy-DbaDatabase
+                    Write-Message -Level Verbose -Message "Opening additional normal connection for all commands that don't require DAC."
+                    $sourceServer = Connect-DbaInstance -SqlInstance $Source.FullName -SqlCredential $SourceSqlCredential
+                } else {
+                    Write-Message -Level Verbose -Message "Opening or reusing normal connection for all commands that don't require DAC."
+                    $sourceServer = Connect-DbaInstance -SqlInstance $Source -SqlCredential $SourceSqlCredential
+                }
+            }
         } catch {
             Stop-Function -Message "Failure" -Category ConnectionError -ErrorRecord $_ -Target $Source
             return
@@ -382,13 +426,21 @@ function Start-DbaMigration {
         if ($Exclude -notcontains 'Credentials') {
             Write-ProgressHelper -StepNumber ($stepCounter++) -Message "Migrating SQL credentials"
             Write-Message -Level Verbose -Message "Migrating SQL credentials"
-            Copy-DbaCredential -Source $sourceserver -Destination $Destination -DestinationSqlCredential $DestinationSqlCredential -Force:$Force
+            if ($dacNeeded) {
+                Copy-DbaCredential -Source $sourceServerDac -Destination $Destination -DestinationSqlCredential $DestinationSqlCredential -Credential $Credential -ExcludePassword:$ExcludePassword -Force:$Force
+            } else {
+                Copy-DbaCredential -Source $sourceserver -Destination $Destination -DestinationSqlCredential $DestinationSqlCredential -Credential $Credential -ExcludePassword:$ExcludePassword -Force:$Force
+            }
         }
 
         if ($Exclude -notcontains 'DatabaseMail') {
             Write-ProgressHelper -StepNumber ($stepCounter++) -Message "Migrating database mail"
             Write-Message -Level Verbose -Message "Migrating database mail"
-            Copy-DbaDbMail -Source $sourceserver -Destination $Destination -DestinationSqlCredential $DestinationSqlCredential -Force:$Force
+            if ($dacNeeded) {
+                Copy-DbaDbMail -Source $sourceServerDac -Destination $Destination -DestinationSqlCredential $DestinationSqlCredential -Credential $Credential -ExcludePassword:$ExcludePassword -Force:$Force
+            } else {
+                Copy-DbaDbMail -Source $sourceserver -Destination $Destination -DestinationSqlCredential $DestinationSqlCredential -Credential $Credential -ExcludePassword:$ExcludePassword -Force:$Force
+            }
         }
 
         if ($Exclude -notcontains 'CentralManagementServer') {
@@ -474,7 +526,11 @@ function Start-DbaMigration {
         if ($Exclude -notcontains 'LinkedServers') {
             Write-ProgressHelper -StepNumber ($stepCounter++) -Message "Migrating linked servers"
             Write-Message -Level Verbose -Message "Migrating linked servers"
-            Copy-DbaLinkedServer -Source $sourceserver -Destination $Destination -DestinationSqlCredential $DestinationSqlCredential -Force:$Force
+            if ($dacNeeded) {
+                Copy-DbaLinkedServer -Source $sourceServerDac -Destination $Destination -DestinationSqlCredential $DestinationSqlCredential -Credential $Credential -ExcludePassword:$ExcludePassword -Force:$Force
+            } else {
+                Copy-DbaLinkedServer -Source $sourceserver -Destination $Destination -DestinationSqlCredential $DestinationSqlCredential -Credential $Credential -ExcludePassword:$ExcludePassword -Force:$Force
+            }
         }
 
         if ($Exclude -notcontains 'DataCollector') {
@@ -547,6 +603,9 @@ function Start-DbaMigration {
         }
     }
     end {
+        if ($dacOpened) {
+            $null = $sourceServerDac | Disconnect-DbaInstance -WhatIf:$false
+        }
         if (Test-FunctionInterrupt) { return }
         $totaltime = ($elapsed.Elapsed.toString().Split(".")[0])
         Write-Message -Level Verbose -Message "SQL Server migration complete."

tests/Start-DbaMigration.Tests.ps1

@@ -13,6 +13,7 @@ Describe $CommandName -Tag UnitTests {
             $expectedParameters += @(
                 "Source",
                 "Destination",
+                "Credential",
                 "DetachAttach",
                 "Reattach",
                 "BackupRestore",
@@ -33,6 +34,7 @@ Describe $CommandName -Tag UnitTests {
                 "KeepCDC",
                 "KeepReplication",
                 "Continue",
+                "ExcludePassword",
                 "Force",
                 "AzureCredential",
                 "MasterKeyPassword",