Skip to content

hyperscale-named-replica-configure.md

Latest commit

 

History

History
254 lines (169 loc) · 14.7 KB

hyperscale-named-replica-configure.md

File metadata and controls

254 lines (169 loc) · 14.7 KB
title Configure and Manage Hyperscale Named Replicas
description Learn how to configure and manage Hyperscale named replica so that a user can access the named replica but not other replicas.
author WilliamDAssafMSFT
ms.author wiassaf
ms.reviewer atsingh, dinethi, rsetlem
ms.date 08/25/2025
ms.service azure-sql-database
ms.subservice scale-out
ms.topic how-to
ms.custom
devx-track-azurecli
devx-track-azurepowershell
sfi-image-nochange

Configure and manage Hyperscale named replicas

[!INCLUDE appliesto-sqldb]

This article provides samples to configure and manage an Azure SQL Database Hyperscale named replica.

Create a Hyperscale named replica

The following sample scenarios guide you to create a named replica WideWorldImporters_NamedReplica for database WideWorldImporters, using the Azure portal, T-SQL, PowerShell, or Azure CLI.

Portal

The following example creates a named replica WideWorldImporters_NamedReplica for database WideWorldImporters using T-SQL. The primary replica uses service level objective HS_Gen5_4, while the named replica uses HS_Gen5_2. Both use the same logical server named contosoeast.

  1. In the Azure portal, view all of your Azure SQL resources and find the database for which you want to create the named replica.

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

    :::image type="content" source="media/named-replicas-configure-portal/azure-create-named-replicas.png" alt-text="Screenshot that shows create named replica step." lightbox="media/named-replicas-configure-portal/azure-create-named-replicas.png":::

  3. Choose Named replica under Replica configuration. Select an existing server or create a new server for the named replica. Enter named replica database name and configure the Compute + storage options if necessary.

    :::image type="content" source="media/named-replicas-configure-portal/azure-choose-named-replica.png" alt-text="Screenshot that shows configuration of named replica." lightbox="media/named-replicas-configure-portal/azure-choose-named-replica.png":::

  4. Optionally, configure a zone redundant Hyperscale named replica. For more information, see Zone redundancy in Azure SQL Database Hyperscale named replicas.

    1. In the Configure database page, select Yes for Would you like to make this database zone redundant?
    2. Add at least one High-Availability Secondary Replica to your configuration.
    3. Select Apply.

  5. Select Review + create, review the information, and then select Create.

  6. The named replica deployment process begins.

    :::image type="content" source="media/named-replicas-configure-portal/azure-deployment-named-replica.png" alt-text="Screenshot that shows named replica deployment status." lightbox="media/named-replicas-configure-portal/azure-deployment-named-replica.png":::

  7. When the deployment is complete, the named replica displays its status.

    :::image type="content" source="media/named-replicas-configure-portal/azure-deployment-complete-named-replica.png" alt-text="Screenshot that shows named replica status after deployment." lightbox="media/named-replicas-configure-portal/azure-deployment-complete-named-replica.png":::

  8. Return to the primary database page, and then select Replicas. Your named replica is listed under Named replicas.

    :::image type="content" source="media/named-replicas-configure-portal/azure-named-replicas.png" alt-text="Screenshot that shows the SQL database primary and named replica." lightbox="media/named-replicas-configure-portal/azure-named-replicas.png":::

T-SQL

The following example creates a named replica WideWorldImporters_NamedReplica for database WideWorldImporters using T-SQL. The primary replica uses service level objective HS_Gen5_4, while the named replica uses HS_Gen5_2. Both use the same logical server named contosoeast.

ALTER DATABASE [WideWorldImporters]
ADD SECONDARY ON SERVER [contosoeast]
WITH (SERVICE_OBJECTIVE = 'HS_Gen5_2', SECONDARY_TYPE = Named, DATABASE_NAME = [WideWorldImporters_NamedReplica]);

PowerShell

The following example creates a named replica WideWorldImporters_NamedReplica for database WideWorldImporters using the PowerShell cmdlet New-AzSqlDatabaseSecondary. The primary replica uses service level objective HS_Gen5_4, while the named replica uses HS_Gen5_2. Both use the same logical server named contosoeast.

New-AzSqlDatabaseSecondary -ResourceGroupName "MyResourceGroup" -ServerName "contosoeast" -DatabaseName "WideWorldImporters" -PartnerResourceGroupName "MyResourceGroup" -PartnerServerName "contosoeast" -PartnerDatabaseName "WideWorldImporters_NamedReplica" -SecondaryType Named -SecondaryServiceObjectiveName HS_Gen5_2

To configure a zone redundant Hyperscale named replica, you must specify both the –ZoneRedundant and -HighAvailabilityReplicaCount input parameters for New-AzSqlDatabaseSecondary.

New-AzSqlDatabaseSecondary -ResourceGroupName "MyResourceGroup" -ServerName "contosoeast" -DatabaseName "WideWorldImporters" -PartnerResourceGroupName "MyResourceGroup" -PartnerServerName "contosoeast" -PartnerDatabaseName "WideWorldImporters_NamedReplica" -SecondaryType Named -SecondaryServiceObjectiveName HS_Gen5_2 -HighAvailabilityReplicaCount 1 -ZoneRedundant

To validate if named replica is created, use Get-AzSqlDatabase:

Get-AzSqlDatabase -DatabaseName "WideWorldImporters_NamedReplica" -ResourceGroupName "MyResourceGroup" -ServerName "contosoeast"

Azure CLI

The following example creates a named replica WideWorldImporters_NamedReplica for database WideWorldImporters using the Azure CLI command az sql db replica create. The primary replica uses service level objective HS_Gen5_4, while the named replica uses HS_Gen5_2. Both use the same logical server named contosoeast.

az sql db replica create -g MyResourceGroup -n WideWorldImporters -s contosoeast --secondary-type named --partner-database WideWorldImporters_NamedReplica --partner-server contosoeast --service-objective HS_Gen5_2

To configure a zone redundant Hyperscale named replica, you must specify both the –zone-redundant and ha-replicas input parameters for az sql db replica create.

az sql db replica create -g MyResourceGroup -n WideWorldImporters -s contosoeast --secondary-type named --partner-database WideWorldImporters_NamedReplica --partner-server contosoeast --service-objective HS_Gen5_2 --ha-replicas 1 -zone-redundant

To validate if a named replica is being created:

az sql db show -g MyResourceGroup -n WideWorldImporters -s contosoeast

As there is no data movement involved, in most cases a named replica will be created in about a minute. Once the named replica is available, it will be visible from the Azure portal or any command-line tool like AZ CLI or PowerShell. A named replica is usable as a regular read-only database.

Connect to a Hyperscale named replica

To connect to a Hyperscale named replica, you must use the connection string for that named replica, referencing its server and database names. There is no need to specify the option ApplicationIntent=ReadOnly as named replicas are always read-only.

Just like for HA replicas, even though the primary, HA, and named replicas share the same data on the same set of page servers, data caches on each named replica are kept in sync with the primary. The sync is maintained by the transaction log service, which forwards log records from the primary to named replicas. As the result, depending on the workload being processed by a named replica, application of the log records might happen at different speeds, and thus different replicas could have different data latency relative to the primary replica.

Modify a Hyperscale named replica

You can define the service level objective of a named replica when you create it, via the ALTER DATABASE command or in any other supported way (Portal, AZ CLI, PowerShell). If you need to change the service level objective after the named replica has been created, you can do it using the ALTER DATABASE ... MODIFY command on the named replica itself.

In the following example, WideWorldImporters_NamedReplica is the named replica of WideWorldImporters database.

Portal

Open named replica database page, and then select Compute + storage. Update the vCores.

:::image type="content" source="media/named-replicas-configure-portal/azure-update-named-replica.png" alt-text="Screenshot that shows named replica service level objective update." lightbox="media/named-replicas-configure-portal/azure-update-named-replica.png":::

T-SQL

ALTER DATABASE [WideWorldImporters_NamedReplica] MODIFY (SERVICE_OBJECTIVE = 'HS_Gen5_4')

PowerShell

Set-AzSqlDatabase -ResourceGroup "MyResourceGroup" -ServerName "contosoeast" -DatabaseName "WideWorldImporters_NamedReplica" -RequestedServiceObjectiveName "HS_Gen5_4"

Azure CLI

az sql db update -g MyResourceGroup -s contosoeast -n WideWorldImporters_NamedReplica --service-objective HS_Gen5_4

Remove a Hyperscale named replica

To remove a Hyperscale named replica, you drop it just like you would a regular database.

Portal

Open named replica database page, and choose Delete option.

:::image type="content" source="media/named-replicas-configure-portal/azure-delete-named-replicas.png" alt-text="Screenshot that shows deletion of named replica." lightbox="media/named-replicas-configure-portal/azure-delete-named-replicas.png":::

T-SQL

Make sure you are connected to the master database of the server with the named replica you want to drop, and then use the following command:

This command drops a database named WideWorldImporters_NamedReplica.

DROP DATABASE [WideWorldImporters_NamedReplica];

PowerShell

This command drops a database named WideWorldImporters_NamedReplica from the logical server contosoeast.

Remove-AzSqlDatabase -ResourceGroupName "MyResourceGroup" -ServerName "contosoeast" -DatabaseName "WideWorldImporters_NamedReplica"

Azure CLI

This command drops a database named WideWorldImporters_NamedReplica from the logical server contosoeast.

az sql db delete -g MyResourceGroup -s contosoeast -n WideWorldImporters_NamedReplica

Important

Named replicas will be automatically removed when the primary replica from which they have been created is deleted.

Optimize named replica configuration

It is recommended to configure the named replica with the same compute size (vCores) as the primary replica. If the primary replica experiences a heavy write workload, a named replica with a lower compute size might not be able to keep up, causing replication lag. To maintain the recoverability SLAs, primary's transaction log rate can be temporarily reduced to allow its secondaries to catch up.

If you choose to create the named replica with a different compute size (vCores) than the primary, monitor the log IO rate on the primary over time. This helps estimate the minimal compute size required for the named replica to sustain the replication load. For more information, consider the following objects:

  • The sys.dm_hs_database_log_rate() dynamic management function (DMF) provides additional details to help understand log rate reduction, if any. It can indicate which specific secondary replica is behind in applying log records and the total size of the unapplied transaction log.
  • To retrieve historical log IO data, use sys.resource_stats view.
  • For recent log IO data with higher granularity that better reflects short-term spikes, use sys.dm_db_resource_stats.

For more information, see to the Azure SQL Database Hyperscale Performance Diagnostics.

Related content