Use PowerShell to add a database to a failover group
Applies to: Azure SQL Database
This PowerShell script example creates a single database in Azure SQL Database, creates a failover group, adds the database to it, and tests failover.
If you don't have an Azure trail subscription, create a trial subscription before you begin.
Note
This article uses the Azure Az PowerShell module, which is the recommended PowerShell module for interacting with Azure. To get started with the Az PowerShell module, see Install Azure PowerShell. To learn how to migrate to the Az PowerShell module, see Migrate Azure PowerShell from AzureRM to Az.
This tutorial requires AZ PowerShell 1.4.0 or later. If you need to upgrade, see Install Azure PowerShell module. If you are running PowerShell locally, you also need to run Connect-AzAccount -Environment AzureChinaCloud
to create a connection with Azure.
Sample scripts
# Add a single Azure SQL Database to a failover group
# Set variables for your server and database
$subscriptionId = '<SubscriptionID>'
$randomIdentifier = $(Get-Random)
$resourceGroupName = "myResourceGroup-$randomIdentifier"
$location = "China East 2"
$adminLogin = "azureuser"
$password = "PWD27!"+(New-Guid).Guid
$serverName = "mysqlserver-$randomIdentifier"
$databaseName = "mySampleDatabase"
$drLocation = "China North 2"
$drServerName = "mysqlsecondary-$randomIdentifier"
$failoverGroupName = "failovergrouptutorial-$randomIdentifier"
# The ip address range that you want to allow to access your server
# Leaving at 0.0.0.0 will prevent outside-of-azure connections
$startIp = "0.0.0.0"
$endIp = "0.0.0.0"
# Show randomized variables
Write-host "Resource group name is" $resourceGroupName
Write-host "Password is" $password
Write-host "Server name is" $serverName
Write-host "DR Server name is" $drServerName
Write-host "Failover group name is" $failoverGroupName
# Set subscription ID
Set-AzContext -SubscriptionId $subscriptionId
# Create a resource group
Write-host "Creating resource group..."
$resourceGroup = New-AzResourceGroup -Name $resourceGroupName -Location $location -Tag @{Owner="SQLDB-Samples"}
$resourceGroup
# Create a server with a system wide unique server name
Write-host "Creating primary logical server..."
$server = New-AzSqlServer -ResourceGroupName $resourceGroupName `
-ServerName $serverName `
-Location $location `
-SqlAdministratorCredentials $(New-Object -TypeName System.Management.Automation.PSCredential `
-ArgumentList $adminLogin, $(ConvertTo-SecureString -String $password -AsPlainText -Force))
$server
# Create a server firewall rule that allows access from the specified IP range
Write-host "Configuring firewall for primary logical server..."
$serverFirewallRule = New-AzSqlServerFirewallRule -ResourceGroupName $resourceGroupName `
-ServerName $serverName `
-FirewallRuleName "AllowedIPs" -StartIpAddress $startIp -EndIpAddress $endIp
$serverFirewallRule
# Create General Purpose Gen5 database with 2 vCore
Write-host "Creating a gen5 2 vCore database..."
$database = New-AzSqlDatabase -ResourceGroupName $resourceGroupName `
-ServerName $serverName `
-DatabaseName $databaseName `
-Edition GeneralPurpose `
-VCore 2 `
-ComputeGeneration Gen5 `
-MinimumCapacity 2 `
-SampleName "AdventureWorksLT"
$database
# Create a secondary server in the failover region
Write-host "Creating a secondary logical server in the failover region..."
$drServer = New-AzSqlServer -ResourceGroupName $resourceGroupName `
-ServerName $drServerName `
-Location $drLocation `
-SqlAdministratorCredentials $(New-Object -TypeName System.Management.Automation.PSCredential `
-ArgumentList $adminlogin, $(ConvertTo-SecureString -String $password -AsPlainText -Force))
$drServer
# Create a failover group between the servers
$failovergroup = Write-host "Creating a failover group between the primary and secondary server..."
New-AzSqlDatabaseFailoverGroup `
�ResourceGroupName $resourceGroupName `
-ServerName $serverName `
-PartnerServerName $drServerName `
�FailoverGroupName $failoverGroupName `
�FailoverPolicy Manual
$failovergroup
# Add the database to the failover group
Write-host "Adding the database to the failover group..."
Get-AzSqlDatabase `
-ResourceGroupName $resourceGroupName `
-ServerName $serverName `
-DatabaseName $databaseName | `
Add-AzSqlDatabaseToFailoverGroup `
-ResourceGroupName $resourceGroupName `
-ServerName $serverName `
-FailoverGroupName $failoverGroupName
Write-host "Successfully added the database to the failover group..."
# Check role of secondary replica
Write-host "Confirming the secondary replica is secondary...."
(Get-AzSqlDatabaseFailoverGroup `
-FailoverGroupName $failoverGroupName `
-ResourceGroupName $resourceGroupName `
-ServerName $drServerName).ReplicationRole
# Failover to secondary server
Write-host "Failing over failover group to the secondary..."
Switch-AzSqlDatabaseFailoverGroup `
-ResourceGroupName $resourceGroupName `
-ServerName $drServerName `
-FailoverGroupName $failoverGroupName
Write-host "Failed failover group successfully to" $drServerName
Write-host "Confirming the secondary server is now primary...."
(Get-AzSqlDatabaseFailoverGroup `
-FailoverGroupName $failoverGroupName `
-ResourceGroupName $resourceGroupName `
-ServerName $drServerName).ReplicationRole
# Revert failover to primary server
Write-host "Failing over failover group to the primary...."
Switch-AzSqlDatabaseFailoverGroup `
-ResourceGroupName $resourceGroupName `
-ServerName $serverName `
-FailoverGroupName $failoverGroupName
Write-host "Failed failover group successfully back to" $serverName
# Show randomized variables
Write-host "Resource group name is" $resourceGroupName
Write-host "Password is" $password
Write-host "Server name is" $serverName
Write-host "DR Server name is" $drServerName
Write-host "Failover group name is" $failoverGroupName
# Clean up resources by removing the resource group
# Write-host "Removing resource group..."
# Remove-AzResourceGroup -ResourceGroupName $resourceGroupName
# Write-host "Resource group removed =" $resourceGroupName
Script explanation
This script uses the following commands. Each command in the table links to command specific documentation.
Command | Notes |
---|---|
New-AzResourceGroup | Creates a resource group in which all resources are stored. |
New-AzSqlServer | Creates a server. |
New-AzSqlServerFirewallRule | Creates a server-level firewall rule for a server. |
New-AzSqlDatabase | Creates a new database. |
New-AzSqlDatabaseFailoverGroup | Creates a new failover group. |
Get-AzSqlDatabase | Gets one or more databases. |
Add-AzSqlDatabaseToFailoverGroup | Adds one or more databases to a failover group. |
Get-AzSqlDatabaseFailoverGroup | Gets or lists failover groups. |
Switch-AzSqlDatabaseFailoverGroup | Executes a failover of a failover group. |
Remove-AzResourceGroup | Removes a resource group |
Next steps
For more information on Azure PowerShell, see Azure PowerShell documentation.
Additional SQL Database PowerShell script samples can be found in the Azure SQL Database PowerShell scripts.