Always On

Move-sqmAlwaysOnListener

Migrates an Availability Group listener from one AG to another on the same WSFC cluster. Removes the listener from the source AG and adds it to the target AG using the existing IP and port. Writes a TXT report with DNS update instructions and verification commands.

Module: sqmSQLTool
Requires: dbatools
ShouldProcess: Yes (High Impact)
Output: PSCustomObject

Execution Flow

START dbatools available? No throw error Yes Read listener from source AG via sys.availability_group_listeners Listener found? No → throw not found Yes Validate target AG exists (Get-DbaAvailabilityGroup) Target AG exists? No → throw not found Yes ShouldProcess? WhatIf Skip ALTER AVAILABILITY GROUP [Source] REMOVE LISTENER [Name] ALTER AVAILABILITY GROUP [Target] ADD LISTENER [Name] (IP, Port) Verify listener on target AG (re-query) Listener present? No Status=VerifyFailed Write TXT report (nslookup / sqlcmd verification) DONE
ConfirmImpact=High — This operation drops the listener from the source AG before re-creating it on the target. If the ADD step fails, the listener is no longer associated with either AG. Always run with -WhatIf first and ensure DNS TTL is set low before executing.
The function writes a TXT report to the output directory containing nslookup and sqlcmd commands to verify DNS propagation and connectivity after the move. DNS update is required if the new AG's primary replica is on a different IP.

Parameters

ParameterTypeRequiredDescription
-SqlInstanceStringRequiredSQL Server instance hosting both AGs (must be primary or have WSFC visibility).
-SqlCredentialPSCredentialOptionalSQL authentication credentials.
-SourceAvailabilityGroupStringRequiredName of the AG currently owning the listener.
-TargetAvailabilityGroupStringRequiredName of the AG that will receive the listener.
-ListenerNameStringRequiredDNS name of the listener to migrate.
-OutputPathStringOptionalDirectory for the TXT report. Default: current directory.
-EnableExceptionSwitchOptionalThrow exceptions immediately on error.
-WhatIfSwitchOptionalPreview actions without making any changes.
-ConfirmSwitchOptionalPrompt before each high-impact action.

Return Value

Returns a single PSCustomObject with: Status, SourceAg, TargetAg, ListenerName, ListenerIp, ListenerPort, DnsUpdateRequired, ReportFile, NextSteps.

Examples

Example 1 — WhatIf first (recommended)

Move-sqmAlwaysOnListener -SqlInstance "SQL01" `
    -SourceAvailabilityGroup "AG_Finance" `
    -TargetAvailabilityGroup "AG_Finance_DR" `
    -ListenerName "ag-finance-listener" `
    -WhatIf

Example 2 — Execute the migration

Move-sqmAlwaysOnListener -SqlInstance "SQL01" `
    -SourceAvailabilityGroup "AG_Finance" `
    -TargetAvailabilityGroup "AG_Finance_DR" `
    -ListenerName "ag-finance-listener" `
    -OutputPath "C:\Reports\AG" -Confirm

Example 3 — Capture result and check DNS requirement

$result = Move-sqmAlwaysOnListener -SqlInstance "SQL01" `
    -SourceAvailabilityGroup "AG_Old" -TargetAvailabilityGroup "AG_New" `
    -ListenerName "my-listener"

if ($result.DnsUpdateRequired) {
    Write-Host "Update DNS — see: $($result.ReportFile)"
}