Work with Hyperscale elastic pools using command-line tools

  • Article

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.

Prerequisites

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

Create a new Hyperscale elastic pool

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

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

Scale up a Hyperscale elastic pool

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

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

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.

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

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.

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"

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.chinacloudapi.cn/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Sql/servers/{serverName}/elasticPools/{elasticPoolName}?api-version=2021-11-01-preview

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

Related content