Working with Hyperscale elastic pools using command-line tools

Applies to: Azure SQL Database

In this article, learn to create, scale, and move databases into a Hyperscale elastic pool using command line tools such as the Azure CLI and PowerShell. In addition to these methods, you can always use the Azure portal for most operations.

Note

Elastic pools for Hyperscale are currently in preview.

Prerequisites

To work with your Hyperscale elastic pool, you should have:

• An Azure subscription. If you don't have an Azure subscription, create a free account.
• A logical server in Azure deployed to a resource group. The examples in this article use the name my-example-rg for the resource group, and my-example-sql-svr for the logical server.
• The latest version of Azure PowerShell Az.Sql.3.11.0 or higher or the Azure CLI Az version 2.40.0 or higher

Create a new Hyperscale elastic pool

You can use the Azure CLI or Azure PowerShell to create a Hyperscale elastic pool.

Azure CLI

Use the az sql elastic-pool create command to create a Hyperscale elastic pool.

The following example creates a Hyperscale elastic pool with four vCores, and two secondary pool replicas:

az sql elastic-pool create --resource-group "my-example-rg" --server "my-example-sql-svr" --name "my_hs_pool" --edition "Hyperscale" --capacity 4 --family Gen5 --ha-replicas 2

The following example creates a zone redundant Hyperscale elastic pool with four vCores and one secondary pool replica:

az sql elastic-pool create --resource-group "myresourcegroup" --server "mylogicalserver" --name "zr-hs-ep" --family Gen5 --edition Hyperscale --capacity 4 --ha-replicas 1 --zone-redundant

PowerShell

Use the New-AzSqlElasticPool cmdlet to create a Hyperscale elastic pool.

The following example creates a Hyperscale elastic pool configured with four vCores, and two secondary pool replicas:

New-AzSqlElasticPool -ResourceGroupName "my-example-rg" -ServerName "my-example-sql-svr" -ElasticPoolName "my_hs_pool" -Edition "Hyperscale" -VCore 4 -ComputeGeneration Gen5 -HighAvailabilityReplicaCount 2

The following example creates zone redundant a Hyperscale elastic pool configured with four vCores, and one secondary pool replica:

New-AzSqlElasticPool -ResourceGroupName "myresourcegroup" -ServerName "mylogicalserver" -ElasticPoolName "zr-hs-ep" -Edition Hyperscale -ComputeGeneration Gen5 -VCore 4 -HighAvailabilityReplicaCount 1 -ZoneRedundant

Scale up a Hyperscale elastic pool

You can use the Azure CLI or Azure PowerShell to scale up an existing Hyperscale elastic pool.

Azure CLI

Use the az sql elastic-pool update command to scale up an existing Hyperscale elastic pool.

The following example scales up an existing Hyperscale elastic pool to 8 vCores and sets the per-DB min and max to 0 and 2, respectively:

az sql elastic-pool update --resource-group "my-example-rg" --server "my-example-sql-svr" --name "my_hs_pool" --capacity 8 --db-min-capacity 0 --db-max-capacity 2

PowerShell

Use the Set-AzSqlElasticPool cmdlet to scale up an existing Hyperscale elastic pool.

The following example scales up an existing Hyperscale elastic pool to 8 vCores and sets the per-DB min and max to 0 and 2, respectively:

Set-AzSqlElasticPool -ResourceGroupName "my-example-rg" -ServerName "my-example-sql-svr" -ElasticPoolName "my_hs_pool" -VCore 8 -DatabaseVCoreMin 0 -DatabaseVCoreMax 2

Scale out (or in) a Hyperscale elastic pool

Use the Azure CLI or Azure PowerShell to add or remove secondary pool replicas for an existing Hyperscale elastic pool - also known as scaling out or scaling in.

Azure CLI

Use the az sql elastic-pool update command to scale out an existing Hyperscale elastic pool by adding a secondary pool replica or scale in an elastic pool by removing secondary pool replicas.

The following example scales out an existing Hyperscale elastic pool to use four secondary pool replicas:

# use the --ha-replicas (--read-replicas can also be used) parameter to specify the new number of high-availability replicas:
az sql elastic-pool update --resource-group "my-example-rg" --server "my-example-sql-svr" --name "my_hs_pool" --ha-replicas 4

The following example scales in an existing Hyperscale elastic pool to use one secondary pool replica:

# use the --ha-replicas (--read-replicas can also be used) parameter to specify the new number of high-availability replicas:
az sql elastic-pool update --resource-group "my-example-rg" --server "my-example-sql-svr" --name "my_hs_pool" --ha-replicas 1

PowerShell

Use the Set-AzSqlElasticPool command to scale out an existing Hyperscale elastic pool by adding a secondary pool replica or scale in an elastic pool by removing secondary pool replicas.

The following example scales out an existing Hyperscale elastic pool to use four secondary pool replicas:

Set-AzSqlElasticPool -ResourceGroupName "my-example-rg" -ServerName "my-example-sql-svr" -ElasticPoolName "my_hs_pool"  -HighAvailabilityReplicaCount 4

The following example scales in an existing Hyperscale elastic pool to use one secondary pool replica:

Set-AzSqlElasticPool -ResourceGroupName "my-example-rg" -ServerName "my-example-sql-svr" -ElasticPoolName "my_hs_pool"  -HighAvailabilityReplicaCount 1

Move an existing database to a Hyperscale elastic pool

You can use the Azure CLI or Azure PowerShell to move an existing database in Azure SQL Database into an existing Hyperscale elastic pool.

Azure CLI

Use the az sql db update command to move an existing database into an existing Hyperscale elastic pool.

The following example moves database my_existing_db into existing Hyperscale elastic pool my_hs_pool:

az sql db update --resource-group "my-example-rg" --server "my-example-sql-svr" --name "my_existing_db" --elastic-pool "my_hs_pool"

PowerShell

Use the Set-AzSqlDatabase cmdlet to move an existing database into an existing Hyperscale elastic pool.

The following example moves database my_existing_db into existing Hyperscale elastic pool my_hs_pool:

Set-AzSqlDatabase -ResourceGroupName "my-example-rg" -ServerName "my-example-sql-svr" -DatabaseName "my_existing_db" -ElasticPoolName "my_hs_pool"

Upgrade an existing elastic pool from Gen5 to premium-series hardware

You can use the Azure CLI or Azure PowerShell to upgrade an existing elastic pool from Gen5 to premium-series hardware.

Azure CLI

Currently unavailable via Azure CLI. Use Azure PowerShell or the Azure portal instead.

PowerShell

Use the Set-AzSqlElasticPool cmdlet to scale up an existing Hyperscale elastic pool.

The following example upgrade an existing Hyperscale elastic pool my_hs_pool to premium-series hardware:

Set-AzSqlElasticPool -ResourceGroupName "my-example-rg" -ServerName "my-example-sql-svr" -ElasticPoolName "my_hs_pool" -ComputeGeneration "PRMS"

Migrate an existing General Purpose database to a zone redundant Hyperscale elastic pool

You can use the Azure CLI or Azure PowerShell to migrate an existing General Purpose database to a zone redundant Hyperscale elastic pool.

Azure CLI

az sql db update --resource-group "myresourcegroup" --server "mylogicalserver" --name "gp_zrs_standalone_db" --elastic-pool "zr-hs-ep" --backup-storage-redundancy Zone

PowerShell

Set-AzSqlDatabase -ResourceGroupName "myResourceGroup" -ServerName "mylogicalserver" -DatabaseName gp1 -ElasticPoolName "my-ZR-Hyperscale-EP" -BackupStorageRedundancy Zone

REST API

Use the 2021-11-01 REST API (or later) to work with secondary replicas for Hyperscale elastic pools.

The following example scales out an existing Hyperscale elastic pool to use four secondary replicas:

PATCH https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Sql/servers/{serverName}/elasticPools/{elasticPoolName}?api-version=2021-11-01-preview

{
  "properties": {
    "highAvailabilityReplicaCount": 4
  }
}

Related content

• Azure SQL Database CLI commands.
• Azure SQL Database PowerShell cmdlets.
• Azure SQL Database elastic pools REST API.
• Hyperscale elastic pools overview.