|
| 1 | +--- |
| 2 | +title: Working with Hyperscale elastic pools using command-line tools |
| 3 | +description: Working with Hyperscale elastic pools using command-line tools such as the Azure CLI and PowerShell. |
| 4 | +author: arvindshmicrosoft |
| 5 | +ms.author: arvindsh |
| 6 | +ms.reviewer: wiassaf, mathoma |
| 7 | +ms.date: 05/21/2023 |
| 8 | +ms.service: sql-database |
| 9 | +ms.subservice: elastic-pools |
| 10 | +ms.topic: conceptual |
| 11 | +ms.custom: |
| 12 | +--- |
| 13 | +# Working with Hyperscale elastic pools using command-line tools |
| 14 | +[!INCLUDE[appliesto-sqldb](../includes/appliesto-sqldb.md)] |
| 15 | + |
| 16 | +In this article, learn to create, scale, and move databases into a [Hyperscale elastic pool](hyperscale-elastic-pool-overview.md) 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. |
| 17 | + |
| 18 | + |
| 19 | +> [!NOTE] |
| 20 | +> Hyperscale elastic pools are in public preview. This preview feature is available for Azure SQL Database (Hyperscale service tier). It is not available for Azure SQL Managed Instance, SQL Server on-premises, SQL Server on Azure VMs, or Azure Synapse Analytics (dedicated SQL pools (formerly SQL DW)). |
| 21 | +
|
| 22 | + |
| 23 | + |
| 24 | +## Prerequisites |
| 25 | + |
| 26 | +To work with your Hyperscale elastic pool, you should have: |
| 27 | + |
| 28 | +- An Azure subscription. If you don't have an Azure subscription, [create a free account](https://azure.microsoft.com/free/). |
| 29 | +- A [logical server in Azure](logical-servers.md) deployed to a [resource group](/azure/azure-resource-manager/management/manage-resource-groups-portal). The examples in this article use the name `my-example-rg` for the resource group, and `my-example-sql-svr` for the logical server. |
| 30 | +- The latest version of Azure PowerShell [Az.Sql.3.11.0 or higher](https://www.powershellgallery.com/packages/Az.Sql/3.11.0) or the Azure CLI [Az version 2.40.0 or higher](/cli/azure/install-azure-cli) |
| 31 | + |
| 32 | + |
| 33 | +## Create a new Hyperscale elastic pool |
| 34 | + |
| 35 | +You can use the Azure CLI or Azure PowerShell to create a Hyperscale elastic pool. |
| 36 | + |
| 37 | +### [Azure CLI](#tab/azure-cli) |
| 38 | + |
| 39 | + |
| 40 | +Use the [az sql elastic-pool create](/cli/azure/sql/elastic-pool#az_sql_elastic_pool_create) command to create a Hyperscale elastic pool. |
| 41 | + |
| 42 | +The following example creates a Hyperscale elastic pool with 4 vCores, and two secondary pool replicas: |
| 43 | + |
| 44 | +```azurecli |
| 45 | +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 |
| 46 | +``` |
| 47 | + |
| 48 | +### [PowerShell](#tab/azure-powershell) |
| 49 | + |
| 50 | +Use the [New-AzSqlElasticPool](/powershell/module/az.sql/new-azsqlelasticpool) cmdlet to create a Hyperscale elastic pool. |
| 51 | + |
| 52 | +The following example creates a Hyperscale elastic pool configured with 4 vCores, and two secondary pool replicas: |
| 53 | + |
| 54 | +```powershell |
| 55 | +New-AzSqlElasticPool -ResourceGroupName "my-example-rg" -ServerName "my-example-sql-svr" -ElasticPoolName "my_hs_pool" -Edition "Hyperscale" -VCore 4 -ComputeGeneration Gen5 -HighAvailabilityReplicaCount 2 |
| 56 | +``` |
| 57 | + |
| 58 | +--- |
| 59 | + |
| 60 | +## Scale up a Hyperscale elastic pool |
| 61 | + |
| 62 | +You can use the Azure CLI or Azure PowerShell to scale up an existing Hyperscale elastic pool. |
| 63 | + |
| 64 | + |
| 65 | +### [Azure CLI](#tab/azure-cli) |
| 66 | + |
| 67 | +Use the [az sql elastic-pool update](/cli/azure/sql/elastic-pool#az-sql-elastic-pool-update) command to scale up an existing Hyperscale elastic pool. |
| 68 | + |
| 69 | +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: |
| 70 | + |
| 71 | +```azurecli |
| 72 | +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 |
| 73 | +``` |
| 74 | + |
| 75 | +### [PowerShell](#tab/azure-powershell) |
| 76 | + |
| 77 | +Use the [Set-AzSqlElasticPool](/powershell/module/az.sql/set-azsqlelasticpool) cmdlet to scale up an existing Hyperscale elastic pool. |
| 78 | + |
| 79 | +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: |
| 80 | + |
| 81 | + |
| 82 | +```powershell |
| 83 | +Set-AzSqlElasticPool -ResourceGroupName "my-example-rg" -ServerName "my-example-sql-svr" -ElasticPoolName "my_hs_pool" -VCore 8 -DatabaseVCoreMin 0 -DatabaseVCoreMax 2 |
| 84 | +``` |
| 85 | + |
| 86 | +--- |
| 87 | + |
| 88 | +## Scale out (or in) a Hyperscale elastic pool |
| 89 | + |
| 90 | +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. |
| 91 | + |
| 92 | + |
| 93 | +### [Azure CLI](#tab/azure-cli) |
| 94 | + |
| 95 | +Use the [az sql elastic-pool update](/cli/azure/sql/elastic-pool#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. |
| 96 | + |
| 97 | +The following example scales out an existing Hyperscale elastic pool to use four secondary pool replicas: |
| 98 | + |
| 99 | +```azurecli |
| 100 | +# use the --ha-replicas (--read-replicas can also be used) parameter to specify the new number of high-availability replicas: |
| 101 | +az sql elastic-pool update --resource-group "my-example-rg" --server "my-example-sql-svr" --name "my_hs_pool" --ha-replicas 4 |
| 102 | +``` |
| 103 | + |
| 104 | +The following example scales in an existing Hyperscale elastic pool to use one secondary pool replica: |
| 105 | + |
| 106 | +```azurecli |
| 107 | +# use the --ha-replicas (--read-replicas can also be used) parameter to specify the new number of high-availability replicas: |
| 108 | +az sql elastic-pool update --resource-group "my-example-rg" --server "my-example-sql-svr" --name "my_hs_pool" --ha-replicas 1 |
| 109 | +``` |
| 110 | + |
| 111 | +### [PowerShell](#tab/azure-powershell) |
| 112 | + |
| 113 | +Use the [Set-AzSqlElasticPool](/powershell/module/az.sql/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. |
| 114 | + |
| 115 | +The following example scales out an existing Hyperscale elastic pool to use four secondary pool replicas: |
| 116 | + |
| 117 | +```powershell |
| 118 | +Set-AzSqlElasticPool -ResourceGroupName "my-example-rg" -ServerName "my-example-sql-svr" -ElasticPoolName "my_hs_pool" -HighAvailabilityReplicaCount 4 |
| 119 | +``` |
| 120 | + |
| 121 | +The following example scales in an existing Hyperscale elastic pool to use one secondary pool replica: |
| 122 | + |
| 123 | +```powershell |
| 124 | +Set-AzSqlElasticPool -ResourceGroupName "my-example-rg" -ServerName "my-example-sql-svr" -ElasticPoolName "my_hs_pool" -HighAvailabilityReplicaCount 1 |
| 125 | +``` |
| 126 | + |
| 127 | +--- |
| 128 | + |
| 129 | +## Move an existing database to a Hyperscale elastic pool |
| 130 | + |
| 131 | +You can use the Azure CLI or Azure PowerShell to move an existing database in Azure SQL Database into an existing Hyperscale elastic pool. |
| 132 | + |
| 133 | +### [Azure CLI](#tab/azure-cli) |
| 134 | + |
| 135 | +Use the [az sql db update](/cli/azure/sql/db#az-sql-db-update) command to move an existing database into an existing Hyperscale elastic pool. |
| 136 | + |
| 137 | +The following example moves database `my_existing_db` into existing Hyperscale elastic pool `my_hs_pool`: |
| 138 | + |
| 139 | +```azurecli |
| 140 | +az sql db update --resource-group "my-example-rg" --server "my-example-sql-svr" --name "my_existing_db" --elastic-pool "my_hs_pool" |
| 141 | +``` |
| 142 | + |
| 143 | +### [PowerShell](#tab/azure-powershell) |
| 144 | + |
| 145 | +Use the the [Set-AzSqlDatabase](/powershell/module/az.sql/set-azsqldatabase) cmdlet to move an existing database into an existing Hyperscale elastic pool. |
| 146 | + |
| 147 | + |
| 148 | +The following example moves database `my_existing_db` into existing Hyperscale elastic pool `my_hs_pool`: |
| 149 | + |
| 150 | +```powershell |
| 151 | +Set-AzSqlDatabase -ResourceGroupName "my-example-rg" -ServerName "my-example-sql-svr" -DatabaseName "my_existing_db" -ElasticPoolName "my_hs_pool" |
| 152 | +``` |
| 153 | + |
| 154 | +--- |
| 155 | + |
| 156 | +## REST API |
| 157 | + |
| 158 | +Use the [2021-11-01-preview](/rest/api/sql/2021-11-01-preview/elastic-pools/update?tabs=HTTP#update-high-availability-replica-count-of-a-hyperscale-elastic-pool) REST API (or later) to work with secondary replicas for Hyperscale elastic pools. |
| 159 | + |
| 160 | +The following example scales out an existing Hyperscale elastic pool to use 4 secondary replicas: |
| 161 | + |
| 162 | +```rest |
| 163 | +PATCH https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Sql/servers/{serverName}/elasticPools/{elasticPoolName}?api-version=2021-11-01-preview |
| 164 | +
|
| 165 | +{ |
| 166 | + "properties": { |
| 167 | + "highAvailabilityReplicaCount": 4 |
| 168 | + } |
| 169 | +} |
| 170 | +``` |
| 171 | + |
| 172 | +## Next steps |
| 173 | + |
| 174 | +- [Azure SQL Database CLI commands](/cli/azure/sql). |
| 175 | +- [Azure SQL Database PowerShell cmdlets](/powershell/module/az.sql/). |
| 176 | +- [Azure SQL Database elastic pools REST API](/rest/api/sql/2021-11-01-preview/elastic-pools/). |
0 commit comments