Always On

Prepare-sqmListenerForMigration

Safely detaches an AG listener from SQL Server before the cluster/AD team deletes or recreates the listener cluster resource — keeping all databases ONLINE throughout. Alias for Invoke-sqmListenerMigrationPrep.

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

Execution Flow

START STEP 1: Query sys.availability_group_listeners — get listener DNS/IP/port Listener found? Status=FAILED, throw STEP 2: Capture DB state BEFORE removal (online count) ShouldProcess: remove listener? Confirmed ALTER AG REMOVE LISTENER Declined STEP 3: Verify all DBs remain ONLINE after removal Any DBs in RECOVERY? CRITICAL: throw error None STEP 4: Write AD-team instruction report (DNS/IP/port/checklist) Return PSCustomObject (Status=READY_FOR_AD_TEAM) DONE
CRITICAL: Run this BEFORE the AD/cluster team deletes the listener cluster resource. Skipping this step causes all AG databases to enter RECOVERY MODE when the cluster resource is deleted. After execution, wait 15–30 minutes for DNS TTL expiry before the cluster team proceeds.
This is an alias for Invoke-sqmListenerMigrationPrep. The second half of the migration workflow is handled by Move-sqmAlwaysOnListener / Complete-sqmListenerMigration.

Parameters

ParameterTypeRequiredDescription
-SqlInstanceStringOptionalPrimary replica hosting the AG. Default: $env:COMPUTERNAME.
-AvailabilityGroupNameStringRequiredName of the Availability Group.
-ListenerNameStringOptionalDNS name of the specific listener to remove. If omitted, the first listener on the AG is used.
-SqlCredentialPSCredentialOptionalSQL authentication credential.
-OutputPathStringOptionalDirectory for the AD-team instruction report. Default: C:\System\WinSrvLog\MSSQL.
-EnableExceptionSwitchOptionalThrows terminating errors instead of returning a Failed status object.
-WhatIf / -ConfirmSwitchOptionalStandard ShouldProcess support (ConfirmImpact=High).

Return Value

Returns a PSCustomObject with: Status (READY_FOR_AD_TEAM / CANCELLED / FAILED), SqlInstance, AvailabilityGroup, ListenerName, ListenerIpOld, ListenerPort, ListenerSubnet, DatabaseCountTotal, DatabaseCountOnline, Timestamp, DocumentationFile, NextStep, WaitTimeMinutes.

Examples

Example 1 — Prepare listener for migration (step 1 of 2)

Prepare-sqmListenerForMigration -SqlInstance "SQL01" -AvailabilityGroupName "ProdAG"
# Step 2: Wait 15-30 min for DNS TTL. AD team recreates cluster resource.
# Step 3: Run Move-sqmAlwaysOnListener / Complete-sqmListenerMigration

Example 2 — Preview without changes

Prepare-sqmListenerForMigration -SqlInstance "SQL01" -AvailabilityGroupName "ProdAG" -WhatIf