Tutorial: Configure active geo-replication and failover (Azure SQL Database)

Applies to: Azure SQL Database

This article shows you how to configure active geo-replication and initiate a failover for Azure SQL Database by using the Azure portal, PowerShell, or the Azure CLI.

Active geo-replication is configured per database. To fail over a group of databases, or if your application requires a stable connection endpoint, consider Failover groups instead.

To complete this tutorial, you need a single Azure SQL Database. To learn how to create a single database with Azure portal, Azure CLI, or PowerShell, see Quickstart: Create a single database - Azure SQL Database.

• You can use the Azure portal to set up Active geo replication across subscriptions as long as both the subscriptions are in the same Microsoft Entra ID tenant.
  • To create a geo-secondary replica in a subscription different from the subscription of the primary in a different Microsoft Entra ID tenant, use the geo-secondary across subscriptions and Microsoft Entra ID tenant T-SQL tutorial.
  • Cross-subscription geo-replication operations including setup and geo-failover are also supported using Databases Create or Update REST API.

The following steps create a new secondary database in a geo-replication partnership.

To add a secondary database, you must be the subscription owner or co-owner.

The secondary database has the same name as the primary database and has, by default, the same service tier and compute size. The secondary database can be a single database or a pooled database. For more information, see DTU-based purchasing model overview and vCore-based purchasing model. After the secondary is created and seeded, data begins replicating from the primary database to the new secondary database.

If your secondary replica is used only for disaster recovery (DR), and doesn't have any read or write workloads, you can save on licensing costs by designating the database for standby when you configure a new active geo-replication relationship. For more information, see license-free standby replica.

az sql db replica create --resource-group ContosoHotel --server contosoeast --name guestlist --partner-server contosowest --family Gen5 --capacity 2 --secondary-type Geo

az sql db replica list-links --name guestlist --resource-group ContosoHotel --server contosowest

Connect-AzAccount -Environment AzureChinaCloud
$subscriptionid = <your subscription id here>
Set-AzContext -SubscriptionId $subscriptionid

$parameters = @{
    ResourceGroupName = 'PrimaryRG'
    ServerName = 'PrimaryServer'
    DatabaseName = 'TestDB'
    PartnerResourceGroupName = 'SecondaryRG'
    PartnerServerName = 'SecondaryServer'
    PartnerDatabaseName = 'TestDB'
}

New-AzSqlDatabaseSecondary @parameters

$parameters = @{
    ResourceGroupName = 'PrimaryRG'
    ServerName = 'PrimaryServer'
    DatabaseName = 'TestDB'
    PartnerResourceGroupName = 'SecondaryRG'
}

Get-AzSqlDatabaseReplicationLink @parameters

The secondary database can be switched to become the primary.

az sql db replica set-primary --name guestlist --resource-group ContosoHotel --server contosowest

$parameters = @{
    ResourceGroupName = 'SecondaryRG'
    ServerName = 'SecondaryServer'
    DatabaseName = 'TestDB'
    PartnerResourceGroupName = 'PrimaryServer'
}

Set-AzSqlDatabaseSecondary @parameters -Failover

The command immediately switches the secondary database into the primary role. This process normally should complete within 30 seconds or less.

Both databases are unavailable, for up to 25 seconds, while the roles are switched. If the primary database has multiple secondary databases, the command automatically reconfigures the other secondaries to connect to the new primary. The entire operation should take less than a minute to complete under normal circumstances.

This operation permanently stops the replication to the secondary database, and changes the role of the secondary to a regular read-write database. If the connectivity to the secondary database is broken, the command succeeds but the secondary doesn't become read-write until after connectivity is restored.

az sql db replica delete-link --name guestlist --resource-group ContosoHotel --server contosoeast --partner-server contosowest

$parameters = @{
    ResourceGroupName = 'SecondaryRG'
    ServerName = 'SecondaryServer'
    DatabaseName = 'TestDB'
    PartnerResourceGroupName = 'PrimaryRG'
    PartnerServerName = 'PrimaryServer'
}
Remove-AzSqlDatabaseSecondary @parameters

• To create a geo-secondary replica in a subscription different from the subscription of the primary in the same Microsoft Entra tenant, you can use the Azure portal or the steps in this section.
• To create a geo-secondary replica in a subscription different from the subscription of the primary in a different Microsoft Entra tenant, you must use SQL authentication and T-SQL as described in the steps in this section. Microsoft Entra authentication for Azure SQL for cross-subscription geo-replication isn't supported when a logical server is in a different Azure tenant

1. Add the IP address of the client machine executing the T-SQL commands in this example, to the server firewalls of both the primary and secondary servers. You can confirm that IP address by executing the following query while connected to the primary server from the same client machine.

   SELECT client_net_address
   FROM sys.dm_exec_connections
   WHERE session_id = @@SPID;
   

   For more information, see Azure SQL Database and Azure Synapse IP firewall rules.

2. In the master database on the primary server, create a SQL authentication login dedicated to active geo-replication setup. Adjust login name and password as needed.

   CREATE LOGIN geodrsetup
       WITH PASSWORD = 'ComplexPassword01';
   

3. In the same database, create a user for the login, and add it to the dbmanager role:

   CREATE USER geodrsetup FOR LOGIN geodrsetup;
   
   ALTER ROLE dbmanager ADD MEMBER geodrsetup;
   

4. Take note of the SID value of the new login. Obtain the SID value using the following query.

   SELECT sid
   FROM sys.sql_logins
   WHERE name = 'geodrsetup';
   

5. Connect to the primary database (not the master database), and create a user for the same login.

   CREATE USER geodrsetup FOR LOGIN geodrsetup;
   

6. In the same database, add the user to the db_owner role.

   ALTER ROLE db_owner ADD MEMBER geodrsetup;
   

7. In the master database on the secondary server, create the same login as on the primary server, using the same name, password, and SID. Replace the hexadecimal SID value in the sample command below with the one obtained in Step 4.

   CREATE LOGIN geodrsetup
       WITH PASSWORD = 'ComplexPassword01', SID = 0x010600000000006400000000000000001C98F52B95D9C84BBBA8578FACE37C3E;
   

8. In the same database, create a user for the login, and add it to the dbmanager role.

   CREATE USER geodrsetup FOR LOGIN geodrsetup;
   
   ALTER ROLE dbmanager ADD MEMBER geodrsetup;
   

9. Connect to the master database on the primary server using the new geodrsetup login, and initiate geo-secondary creation on the secondary server. Adjust database name and secondary server name as needed. Once the command is executed, you can monitor geo-secondary creation by querying the sys.dm_geo_replication_link_status view in the primary database, and the sys.dm_operation_status view in the master database on the primary server. The time needed to create a geo-secondary depends on the primary database size.

   alter database [dbrep] add secondary on server [servername];
   

10. After the geo-secondary is successfully created, the users, logins, and firewall rules created by this procedure can be removed.

• Active geo-replication
• Failover groups overview & best practices (Azure SQL Database)
• Overview of business continuity with Azure SQL Database
• Configure a license-free standby replica for Azure SQL Database