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 for Azure SQL Database using the Azure portal or Azure CLI and to initiate failover.

For failover groups, see Failover groups with Azure SQL Database and Failover groups with Azure SQL Managed Instance.

Prerequisites

This tutorial shows you how to configure a database for active geo-replication. To learn how to create a single database with Azure portal, Azure CLI, Azure CLI (sql up), or PowerShell, see Quickstart: Create a single database - Azure SQL Database.

Add a secondary database

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 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. Review license-free standby replica to learn more.

Note

If the partner database already exists, (for example, as a result of terminating a previous geo-replication relationship) the command fails.

  1. In the Azure portal, browse to the database that you want to set up for geo-replication.

  2. On the SQL Database page, select your database, scroll to Data management, select Replicas, and then select Create replica.

    Screenshot that shows the Configure geo-replication option.

  3. Select or create the server for the secondary database, and configure the Compute + storage options if necessary. You can select any region for your secondary server, but we recommend the paired region.

    Screenshot that shows the Create and configure replica screen.

    Optionally, you can add a secondary database to an elastic pool. To create the secondary database in a pool, select Yes next to Want to use SQL elastic pool? and select a pool on the target server. A pool must already exist on the target server. This workflow doesn't create a pool.

  4. Click Review + create, review the information, and then click Create.

  5. The secondary database is created and the deployment process begins.

    Screenshot that shows the deployment status of the secondary database.

  6. When the deployment is complete, the secondary database displays its status.

    Screenshot that shows the secondary database status after deployment.

  7. Return to the primary database page, and then select Replicas. Your secondary database is listed under Geo replicas.

    Screenshot that shows the SQL database primary and geo replicas.

Initiate a failover

The secondary database can be switched to become the primary.

  1. In the Azure portal, browse to the primary database in the geo-replication partnership.

  2. Scroll to Data management, and then select Replicas.

  3. In the Geo replicas list, select the database you want to become the new primary, select the ellipsis, and then select Forced failover.

    Screenshot that shows selecting forced failover from the drop-down.

  4. Select Yes to begin the failover.


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

There's a short period during which both databases are unavailable, on the order of 0 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.

Remove secondary database

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.

  1. In the Azure portal, browse to the primary database in the geo-replication partnership.
  2. Select Replicas.
  3. In the Geo replicas list, select the database you want to remove from the geo-replication partnership, select the ellipsis, and then select Stop replication.
  4. A confirmation window opens. Click Yes to remove the database from the geo-replication partnership. (Set it to a read-write database not part of any replication.)

Cross-subscription geo-replication

Use Transact-SQL (T-SQL) create a geo-secondary in a subscription different from the subscription of the primary (whether under the same tenant of Microsoft Entra ID (formerly Azure Active Directory) or not), follow the steps in this section.

  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 Configure firewall.

  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.

Note

Cross-subscription geo-replication operations including setup and geo-failover are only supported using REST API & T-SQL commands.

Adding a geo-secondary using T-SQL is not supported when connecting to the primary server over a private endpoint. If a private endpoint is configured but public network access is allowed, adding a geo-secondary is supported when connected to the primary server from a public IP address. Once a geo-secondary is added, public network access can be denied.

Creating a geo-secondary on a logical server in a different Microsoft Entra tenant is not supported when Microsoft Entra-only authentication is enabled on either primary or secondary logical server.

Next steps