Manage Azure SQL Managed Instance long-term backup retention

An active Azure subscription.

Prepare your environment for the Azure CLI.

If you prefer to run CLI reference commands locally, install the Azure CLI. If you're running on Windows or macOS, consider running Azure CLI in a Docker container. For more information, see How to run the Azure CLI in a Docker container.

• If you're using a local installation, sign in to the Azure CLI by using the az login command. To finish the authentication process, follow the steps displayed in your terminal. For other sign-in options, see Sign in with the Azure CLI.

• When you're prompted, install the Azure CLI extension on first use. For more information about extensions, see Use extensions with the Azure CLI.

• Run az version to find the version and dependent libraries that are installed. To upgrade to the latest version, run az upgrade.

Prepare your environment for PowerShell.

For Get-AzSqlInstanceDatabaseLongTermRetentionBackup and Restore-AzSqlInstanceDatabase, you need to be a member of one of the following roles:

• Subscription Owner role or
• SQL Managed Instance Contributor role or
• Custom role with the following permissions:
  • Microsoft.Sql/locations/longTermRetentionManagedInstanceBackups/read
  • Microsoft.Sql/locations/longTermRetentionManagedInstances/longTermRetentionManagedInstanceBackups/read
  • Microsoft.Sql/locations/longTermRetentionManagedInstances/longTermRetentionDatabases/longTermRetentionManagedInstanceBackups/read

For Remove-AzSqlInstanceDatabaseLongTermRetentionBackup, you need to be a member of one of the following roles:

• Subscription Owner role or
• Custom role with the following permission:
  • Microsoft.Sql/locations/longTermRetentionManagedInstances/longTermRetentionDatabases/longTermRetentionManagedInstanceBackups/delete

1. In the Azure portal, select your managed instance and then select Backups. On the Retention policies tab, select the database(s) on which you want to set or modify long-term backup retention policies. Changes will not apply to any databases left unselected.

   

2. In the Configure policies pane, specify your desired retention period for weekly, monthly, or yearly backups. Choose a retention period of '0' to indicate that no long-term backup retention should be set.

   

3. When complete, select Apply.

1. Run the az sql midb show command to get the details for the SQL Managed Instance database.

   az sql midb show /
   --resource-group mygroup /
   --managed-instance myinstance /
   --name mymanageddb /
   --subscription mysubscription
   

2. Run the az sql midb ltr-policy set command to create an LTR policy. The following example sets a long-term retention policy for 12 weeks for the weekly backup.

   az sql midb ltr-policy set /
   --resource-group mygroup /
   --managed-instance myinstance /
   --name mymanageddb /
   --weekly-retention "P12W"
   

   This example sets a retention policy for 12 weeks for the weekly backup, 5 years for the yearly backup, and the week of April 15 in which to take the yearly LTR backup.

   az sql midb ltr-policy set /
   --resource-group mygroup /
   --managed-instance myinstance /
   --name mymanageddb /
   --weekly-retention "P12W" /
   --yearly-retention "P5Y" /
   --week-of-year 16
   

# get the Managed Instance
$subId = "<subscriptionId>"
$instanceName = "<instanceName>"
$resourceGroup = "<resourceGroupName>"
$dbName = "<databaseName>"

Connect-AzAccount -Environment AzureChinaCloud

Select-AzSubscription -SubscriptionId $subId

$instance = Get-AzSqlInstance -Name $instanceName -ResourceGroupName $resourceGroup

# create LTR policy with WeeklyRetention = 12 weeks. MonthlyRetention and YearlyRetention = 0 by default.
$LTRPolicy = @{
    InstanceName = $instanceName 
    DatabaseName = $dbName 
    ResourceGroupName = $resourceGroup 
    WeeklyRetention = 'P12W'
}
Set-AzSqlInstanceDatabaseBackupLongTermRetentionPolicy @LTRPolicy

# create LTR policy with WeeklyRetention = 12 weeks, YearlyRetention = 5 years and WeekOfYear = 16 (week of April 15). MonthlyRetention = 0 by default.
$LTRPolicy = @{
    InstanceName = $instanceName 
    DatabaseName = $dbName 
    ResourceGroupName = $resourceGroup 
    WeeklyRetention = 'P12W' 
    YearlyRetention = 'P5Y' 
    WeekOfYear = '16'
}
Set-AzSqlInstanceDatabaseBackupLongTermRetentionPolicy @LTRPolicy

To view available long-term backups from the Azure portal, follow these steps:

1. In the Azure portal, select your managed instance and then select Backups. On the Available backups tab, select the database for which you want to see available backups. Select Manage.

   

2. In the Manage backups pane, review the available backups.

   

You can also restore from this page by choosing the backup and selecting Restore.

Alternatively, to restore a backup from long-term retention by using the Azure portal, follow these steps:

1. Sign in to the Azure portal.

2. Go to the target SQL Managed Instance where you plan to restore your database to.

3. On the Overview page, choose + New database to open the Create Azure SQL Managed Database page.

   

4. On the Basics tab of the Create Azure SQL Managed Database page, provide subscription and resource group details under Project details. Then, under Database details provide the new name of the database you plan to restore. Confirm the correct managed instance is listed in the dropdown list. Then select Next: Data source >

   

5. On the Data source tab, choose Point-in-time restore under Use existing data. Provide the subscription, resource group and managed instance that contains the source database. From the Managed database dropdown list, choose the database you want to restore, and then choose the point in time you want to restore the database from. The source and target instance can be the same, or two different instances. Select Next : Additional settings >

   

6. On the Additional settings tab, you can check the box to inherit the retention policy from the source database, or, alternatively, you can select Configure retention to open the Configure policies page, and set your desired retention policies for your restored database. When finished, select Review + create.

   

7. On Review + create, when validation is successful, select Create to restore your database.

This action starts the restore process, which creates a new database and populates it with data from the original database at the specified point in time. For more information about the recovery process, see Recovery time.

View LTR policies

Run the az sql midb ltr-policy show command to view the LTR policy for a single database within an instance.

az sql midb ltr-policy show \
    --resource-group mygroup \
    --managed-instance myinstance \
    --name mymanageddb

View LTR backups

Use the az sql midb ltr-backup list command to view the LTR backups within an instance.

az sql midb ltr-backup list \
    --resource-group mygroup \
    --location chinanorth3 \
    --managed-instance myinstance

Restore from LTR backups

Run the az sql midb ltr-backup restore command to restore your database from an LTR backup. You can run az sql midb ltr-backup show to get the backup-id.

1. Create a variable for the backup-id with the command az sql db ltr-backup show for future use.

    get_backup_id=$(az sql midb ltr-backup show
       --location chinanorth3 \
       --managed-instance myinstance \
       --database mydb \
       --name "3214b3fb-fba9-43e7-96a3-09e35ffcb336;132292152080000000" \
       --query 'id' \
       --output tsv)
   

2. Restore your database from an LTR backup

   az sql midb ltr-backup restore \
       --dest-database targetmidb \
       --dest-mi myinstance \
       --dest-resource-group mygroup \
       --backup-id $get_backup_id
   

View LTR policies

This example shows how to list the LTR policies within an instance for a single database.

# gets the current version of LTR policy for a database
$LTRPolicy = @{
    InstanceName = $instanceName 
    DatabaseName = $dbName 
    ResourceGroupName = $resourceGroup
}
Get-AzSqlInstanceDatabaseBackupLongTermRetentionPolicy @LTRPolicy 

This example shows how to list the LTR policies for all of the databases on an instance.

# gets the current version of LTR policy for all of the databases on an instance

$Databases = Get-AzSqlInstanceDatabase -ResourceGroupName $resourceGroup -InstanceName $instanceName

$LTRParams = @{
    InstanceName = $instanceName
    ResourceGroupName = $resourceGroup
}

foreach($database in $Databases.Name){
    Get-AzSqlInstanceDatabaseBackupLongTermRetentionPolicy @LTRParams  -DatabaseName $database
 }

Clear an LTR policy

This example shows how to clear an LTR policy from a database.

# remove the LTR policy from a database
$LTRPolicy = @{
    InstanceName = $instanceName 
    DatabaseName = $dbName 
    ResourceGroupName = $resourceGroup 
    RemovePolicy = $true
}
Set-AzSqlInstanceDatabaseBackupLongTermRetentionPolicy @LTRPolicy

View LTR backups

This example shows how to list the LTR backups within an instance.

$instance = Get-AzSqlInstance -Name $instanceName -ResourceGroupName $resourceGroup

# get the list of all LTR backups in a specific Azure region
# backups are grouped by the logical database id, within each group they are ordered by the timestamp, the earliest backup first
Get-AzSqlInstanceDatabaseLongTermRetentionBackup -Location $instance.Location

# get the list of LTR backups from the Azure region under the given managed instance
$LTRBackupParam = @{
    Location = $instance.Location 
    InstanceName = $instanceName
}
Get-AzSqlInstanceDatabaseLongTermRetentionBackup @LTRBackupParam

# get the LTR backups for a specific database from the Azure region under the given managed instance
$LTRBackupParam = @{
    Location = $instance.Location 
    InstanceName = $instanceName
    DatabaseName = $dbName
}
Get-AzSqlInstanceDatabaseLongTermRetentionBackup @LTRBackupParam

# list LTR backups only from live databases (you have option to choose All/Live/Deleted)
$LTRBackupParam = @{
    Location = $instance.Location 
    DatabaseState = 'Live'
}
Get-AzSqlInstanceDatabaseLongTermRetentionBackup @LTRBackupParam

# only list the latest LTR backup for each database
$LTRBackupParam = @{
    Location = $instance.Location 
    InstanceName = $instanceName
    OnlyLatestPerDatabase = $true
}
Get-AzSqlInstanceDatabaseLongTermRetentionBackup @LTRBackupParam 

Restore from LTR backups

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.

# restore a specific LTR backup as an P1 database on the instance $instanceName of the resource group $resourceGroup
$LTRBackupParam = @{
    Location = $instance.Location 
    InstanceName = $instanceName
    DatabaseName = $dbname
    OnlyLatestPerDatabase = $true
}
$ltrBackup = Get-AzSqlInstanceDatabaseLongTermRetentionBackup @LTRBackupParam 

$RestoreLTRParam = @{
    TargetInstanceName          = $instanceName 
    TargetResourceGroupName     = $resourceGroup 
    TargetInstanceDatabaseName  = $dbName
    FromLongTermRetentionBackup = $true
    ResourceId                  = $ltrBackup.ResourceId 
}
Restore-AzSqlInstanceDatabase @RestoreLTRParam

1. In the Azure portal, navigate to the SQL managed instance.
2. Select Backups. To view the available LTR backups for a specific database, select Manage under the Available LTR backups column. A pane appears with a list of the available LTR backups for the selected database.
3. In the Available LTR backups pane that appears, review the available backups. Select a backup to delete. Select Delete.

1. Run az sql midb ltr-backup list to get the backup name.

2. Run the az sql midb ltr-backup delete command to remove an LTR backup.

   az sql midb ltr-backup delete \
       --location chinanorth3 \
       --managed-instance myinstance \
       --database mymanageddb \
       --name "3214b3fb-fba9-43e7-96a3-09e35ffcb336;132292152080000000"
   

This example shows how to delete the earliest LTR backup from the list of backups. This sample gets the list of LTR backups for a specific database from the Azure region under the given SQL managed instance.

# remove the earliest backup
# get the LTR backups for a specific database from the Azure region under the given SQL managed instance
$LTRBackupParam = @{
    Location = $instance.Location 
    InstanceName = $instanceName
    DatabaseName = $dbName
}
$ltrBackups = Get-AzSqlInstanceDatabaseLongTermRetentionBackup @LTRBackupParam
$ltrBackup = $ltrBackups[0]
Remove-AzSqlInstanceDatabaseLongTermRetentionBackup -ResourceId $ltrBackup.ResourceId