|
| 1 | +--- |
| 2 | +title: "Managed instance: Long-term backup retention (PowerShell)" |
| 3 | +description: "Learn how to store and restore automated backups on separate Azure Blob storage containers for an Azure SQL Database managed instance using PowerShell." |
| 4 | +services: sql-database |
| 5 | +ms.service: sql-database |
| 6 | +ms.subservice: backup-restore |
| 7 | +ms.custom: |
| 8 | +ms.devlang: |
| 9 | +ms.topic: conceptual |
| 10 | +author: anosov1960 |
| 11 | +ms.author: sashan |
| 12 | +ms.reviewer: mathoma, carlrab |
| 13 | +manager: craigg |
| 14 | +ms.date: 04/14/2020 |
| 15 | +--- |
| 16 | +# Manage Azure SQL Database managed instance long-term backup retention (PowerShell) |
| 17 | + |
| 18 | +In Azure SQL Database managed instance, you can configure a [long-term backup retention](sql-database-long-term-retention.md#managed-instance-support) policy (LTR) as a limited public preview feature. This allows you to to automatically retain database backups in separate Azure Blob storage containers for up to 10 years. You can then recover a database using these backups using PowerShell. |
| 19 | + |
| 20 | + > [!IMPORTANT] |
| 21 | + > LTR for managed instances is currently in limited preview and available for EA and CSP subscriptions on a case by case basis. To request enrollment, please create an [Azure support ticket](https://azure.microsoft.com/support/create-ticket/) under the support topic **Backup, Restore, and Business Continuity/Long-term backup retention**. |
| 22 | +
|
| 23 | + |
| 24 | +The following sections show you how to use PowerShell to configure the long-term backup retention, view backups in Azure SQL storage, and restore from a backup in Azure SQL storage. |
| 25 | + |
| 26 | +## RBAC roles to manage long-term retention |
| 27 | + |
| 28 | +For **Get-AzSqlInstanceDatabaseLongTermRetentionBackup** and **Restore-AzSqlInstanceDatabase**, you will need to have one of the following roles: |
| 29 | + |
| 30 | +- Subscription Owner role or |
| 31 | +- SManaged Instance Contributor role or |
| 32 | +- Custom role with the following permissions: |
| 33 | + |
| 34 | + ```Microsoft.Sql/locations/longTermRetentionManagedInstanceBackups/read``` |
| 35 | + ```Microsoft.Sql/locations/longTermRetentionManagedInstances/longTermRetentionManagedInstanceBackups/read``` |
| 36 | + ```Microsoft.Sql/locations/longTermRetentionManagedInstances/longTermRetentionDatabases/longTermRetentionManagedInstanceBackups/read``` |
| 37 | + |
| 38 | +For **Remove-AzSqlInstanceDatabaseLongTermRetentionBackup**, you will need to have one of the following roles: |
| 39 | + |
| 40 | +- Subscription Owner role or |
| 41 | +- Custom role with the following permission: |
| 42 | + |
| 43 | + ```Microsoft.Sql/locations/longTermRetentionManagedInstances/longTermRetentionDatabases/longTermRetentionManagedInstanceBackups/delete``` |
| 44 | + |
| 45 | +> [!NOTE] |
| 46 | +> The SManaged Instance Contributor role does not have permission to delete LTR backups. |
| 47 | +
|
| 48 | +RBAC permissions could be granted in either *subscription* or *resource group* scope. However, to access LTR backups that belong to a dropped instance, the permission must be granted in the *subscription* scope of that instance. |
| 49 | + |
| 50 | +```Microsoft.Sql/locations/longTermRetentionManagedInstances/longTermRetentionDatabases/longTermRetentionManagedInstanceBackups/delete``` |
| 51 | + |
| 52 | +## Create an LTR policy |
| 53 | + |
| 54 | +```powershell |
| 55 | +# get the Managed Instance |
| 56 | +$subId = "<subscriptionId>" |
| 57 | +$instanceName = "<instanceName>" |
| 58 | +$resourceGroup = "<resourceGroupName>" |
| 59 | +$dbName = "<databaseName>" |
| 60 | +
|
| 61 | +Connect-AzAccount |
| 62 | +Select-AzSubscription -SubscriptionId $subId |
| 63 | +
|
| 64 | +$instance = Get-AzSqlInstance -Name $instanceName -ResourceGroupName $resourceGroup |
| 65 | +
|
| 66 | +# create LTR policy with WeeklyRetention = 12 weeks. MonthlyRetention and YearlyRetention = 0 by default. |
| 67 | +Set-AzSqlInstanceDatabaseBackupLongTermRetentionPolicy -InstanceName $instanceName ` |
| 68 | + -DatabaseName $dbName -ResourceGroupName $resourceGroup -WeeklyRetention P12W |
| 69 | +
|
| 70 | +# create LTR policy with WeeklyRetention = 12 weeks, YearlyRetention = 5 years and WeekOfYear = 16 (week of April 15). MonthlyRetention = 0 by default. |
| 71 | +Set-AzSqlInstanceDatabaseBackupLongTermRetentionPolicy -InstanceName $instanceName ` |
| 72 | + -DatabaseName $dbName -ResourceGroupName $resourceGroup -WeeklyRetention P12W -YearlyRetention P5Y -WeekOfYear 16 |
| 73 | +
|
| 74 | +``` |
| 75 | + |
| 76 | +## View LTR policies |
| 77 | + |
| 78 | +This example shows how to list the LTR policies within an instance |
| 79 | + |
| 80 | +```powershell |
| 81 | +# gets the current version of LTR policy for the database |
| 82 | +$ltrPolicies = Get-AzSqlInstanceDatabaseBackupLongTermRetentionPolicy -InstanceName $instanceName ` |
| 83 | + -DatabaseName $dbName -ResourceGroupName $resourceGroup |
| 84 | +
|
| 85 | +``` |
| 86 | + |
| 87 | +## Clear an LTR policy |
| 88 | + |
| 89 | +This example shows how to clear an LTR policy from a database |
| 90 | + |
| 91 | +```powershell |
| 92 | +Set-AzSqlInstanceDatabaseBackupLongTermRetentionPolicy -InstanceName $instanceName ` |
| 93 | + -DatabaseName $dbName -ResourceGroupName $resourceGroup -RemovePolicy |
| 94 | +``` |
| 95 | + |
| 96 | +## View LTR backups |
| 97 | + |
| 98 | +This example shows how to list the LTR backups within an instance. |
| 99 | + |
| 100 | +```powershell |
| 101 | +# get the list of all LTR backups in a specific Azure region |
| 102 | +# backups are grouped by the logical database id, within each group they are ordered by the timestamp, the earliest backup first |
| 103 | +$ltrBackups = Get-AzSqlInstanceDatabaseLongTermRetentionBackup -Location $instance.Location |
| 104 | +
|
| 105 | +# get the list of LTR backups from the Azure region under the given managed instance |
| 106 | +$ltrBackups = Get-AzSqlInstanceDatabaseLongTermRetentionBackup -Location $instance.Location -InstanceName $instanceName |
| 107 | +
|
| 108 | +# get the LTR backups for a specific database from the Azure region under the given managed instance |
| 109 | +$ltrBackups = Get-AzSqlInstanceDatabaseLongTermRetentionBackup -Location $instance.Location -InstanceName $instanceName -DatabaseName $dbName |
| 110 | +
|
| 111 | +# list LTR backups only from live databases (you have option to choose All/Live/Deleted) |
| 112 | +$ltrBackups = Get-AzSqlInstanceDatabaseLongTermRetentionBackup -Location $instance.Location -DatabaseState Live |
| 113 | +
|
| 114 | +# only list the latest LTR backup for each database |
| 115 | +$ltrBackups = Get-AzSqlInstanceDatabaseLongTermRetentionBackup -Location $instance.Location -InstanceName $instanceName -OnlyLatestPerDatabase |
| 116 | +
|
| 117 | +``` |
| 118 | + |
| 119 | +## Delete LTR backups |
| 120 | + |
| 121 | +This example shows how to delete an LTR backup from the list of backups. |
| 122 | + |
| 123 | +```powershell |
| 124 | +# remove the earliest backup |
| 125 | +$ltrBackup = $ltrBackups[0] |
| 126 | +Remove-AzSqlInstanceDatabaseLongTermRetentionBackup -ResourceId $ltrBackup.ResourceId |
| 127 | +``` |
| 128 | + |
| 129 | +> [!IMPORTANT] |
| 130 | +> Deleting LTR backup is non-reversible. To delete an LTR backup after the instance has been deleted you must have Subscription scope permission. You can set up notifications about each delete in Azure Monitor by filtering for operation 'Deletes a long term retention backup'. The activity log contains information on who and when made the request. See [Create activity log alerts](../azure-monitor/platform/alerts-activity-log.md) for detailed instructions. |
| 131 | +
|
| 132 | +## Restore from LTR backups |
| 133 | + |
| 134 | +This example shows how to restore from an LTR backup. Note, this interface did not change but the resource id parameter now requires the LTR backup resource id. |
| 135 | + |
| 136 | +```powershell |
| 137 | +# restore a specific LTR backup as an P1 database on the instance $instanceName of the resource group $resourceGroup |
| 138 | +Restore-AzSqlInstanceDatabase -FromLongTermRetentionBackup -ResourceId $ltrBackup.ResourceId ` |
| 139 | + -TargetInstanceName $instanceName -TargetResourceGroupName $resourceGroup -TargetInstanceDatabaseName $dbName |
| 140 | +
|
| 141 | +``` |
| 142 | + |
| 143 | +> [!IMPORTANT] |
| 144 | +> To restore from an LTR backup after the instance has been deleted, you must have permissions scoped to the subscription of the instance and that subscription must be active. You must also omit the optional -ResourceGroupName parameter. |
| 145 | +
|
| 146 | +> [!NOTE] |
| 147 | +> From here, you can connect to the restored database using SQL Server Management Studio to perform needed tasks, such as to extract a bit of data from the restored database to copy into the existing database or to delete the existing database and rename the restored database to the existing database name. See [point in time restore](sql-database-recovery-using-backups.md#point-in-time-restore). |
| 148 | +
|
| 149 | +## Next steps |
| 150 | + |
| 151 | +- To learn about service-generated automatic backups, see [automatic backups](sql-database-automated-backups.md) |
| 152 | +- To learn about long-term backup retention, see [long-term backup retention](sql-database-long-term-retention.md) |
0 commit comments