Restore a deleted container or database to the same Azure Cosmos DB account (preview)

Article
07/04/2023

APPLIES TO: NoSQL MongoDB Gremlin Table

The Azure Cosmos DB point-in-time same-account restore feature helps you recover from an accidental deletion of a container or database. This feature restores the deleted database or container to the same, existing account in any region in which backups exist. Continuous backup mode allows you to restore to any point of time within the last 30 days.

Prerequisites

An Azure subscription. If you don't have an Azure subscription, create a free Azure account before you begin.
An Azure Cosmos DB account. You can choose one of the following options for an Azure Cosmos DB account:
- Use an existing Azure Cosmos DB account.
- Create a new Azure Cosmos DB account in your Azure subscription.
- Create a Try Azure Cosmos DB free account with no commitment.

Restore a deleted container or database

Use the Azure portal, the Azure CLI, Azure PowerShell, or an Azure Resource Manager template to restore a deleted container or database in the same, existing account.

Use the Azure portal to restore a deleted container or database. Child containers are also restored.

Go to the Azure portal.
Go to your Azure Cosmos DB account, and then go to the Point In Time Restore page.

Note

The restore page in Azure portal is populated only if you have the Microsoft.DocumentDB/locations/restorableDatabaseAccounts/*/read permission. To learn more about this permission, see Backup and restore permissions.
Select the Restore to same account tab.
For Database, enter a search query to filter the event feed for relevant deletion events for a container or a database.
Next, specify Start and End values to create a time window to use to filter deletion events.

Note

The Start filter is limited to at most 30 days before the present date.
Select Refresh to update the list of events for different resource types with your filters applied.
Verify the time, and then select Restore to start restoration of the selected resource that was previously deleted.

Important

No more than three restore operations can be active at any time on the same account. Deleting the source account while a restore operation is in progress might result in the failure of the restore operation.

Note

The event feed displays resources as Not restorable. The feed provides more information about why the resource can't be restored. In most cases, you must restore the parent database before you can restore any of the database's child containers.
After you initiate a restore operation, track the operation by using the notifications area of the Azure portal. The notification provides the status of the resource that's being restored. While restore is in progress, the status of the container is Creating. After the restore operation completes, the status changes to Online.

Use the Azure CLI to restore a deleted container or database. Child containers are also restored.

Important

The cosmosdb-preview extension for Azure CLI version 0.24.0 or later is required to access the in-account restore command. If you do not have the preview version installed, run az extension add --name cosmosdb-preview --version 0.24.0.

Retrieve a list of all live and deleted restorable database accounts by using az cosmosdb restorable-database-account list:

az cosmosdb restorable-database-account list \
    --account-name <name-of-account>

[
  {
    "accountName": "deleted-account-1",
    "apiType": "Sql",
    "creationTime": "2020-08-02T22:23:00.095870+00:00",
    "deletionTime": "2020-08-02T22:26:13.483175+00:00",
    "id": "/subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.DocumentDB/locations/westus/restorableDatabaseAccounts/abcd1234-d1c0-4645-a699-abcd1234",
    "location": "West US",
    "name": "abcd1234-d1c0-4645-a699-abcd1234",
    "restorableLocations": [
      {
        "locationName": "West US"
      },
      {
        "locationName": "East US"
      }
    ]
  }
]

Use az cosmosdb sql restorable-database list to list all restorable versions of databases for live accounts:
```
az cosmosdb sql restorable-database list \
    --instance-id <instance-id-of-account> \
    --location <location>
```
Note

Listing all the restorable database deletion events allows you to choose the right database in a scenario in which the actual time of existence is unknown. If the event feed contains the Delete operation type in its response, then it’s a deleted database, and it can be restored within the same account. The restore time stamp can be set to any time stamp before the deletion time stamp and within the retention window.
Use az cosmosdb sql restorable-container list to list all the versions of restorable containers within a specific database:
```
az cosmosdb sql restorable-container list \
    --instance-id <instance-id-of-account> \
    --database-rid <owner-resource-id-of-database> \
    --location <location>
```
Note

Listing all the restorable database deletion events allows you to choose the right container in a scenario in which the actual time of existence is unknown. If the event feed contains the Delete operation type in its response, then it’s a deleted container, and it can be restored within the same account. The restore time stamp can be set to any time stamp before the deletion time stamp and within the retention window.

Initiate a restore operation for a deleted database by using az cosmosdb sql database restore:

az cosmosdb sql database restore \
     --resource-group <resource-group-name> \ 
     --account-name <account-name> \  
     --name <database-name> \
     --restore-timestamp <timestamp>

Initiate a restore operation for a deleted container by using az cosmosdb sql container restore:

az cosmosdb sql container restore \
     --resource-group <resource-group-name> \ 
     --account-name <account-name> \  
     --database-name <database-name> \
    --name <container-name> \
     --restore-timestamp <timestamp>

Retrieve a list of all live and deleted restorable database accounts by using az cosmosdb restorable-database-account list:

az cosmosdb restorable-database-account list \
    --account-name <name-of-account>

[
  {
    "accountName": "deleted-account-1",
    "apiType": "Sql",
    "creationTime": "2020-08-02T22:23:00.095870+00:00",
    "deletionTime": "2020-08-02T22:26:13.483175+00:00",
    "id": "/subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.DocumentDB/locations/westus/restorableDatabaseAccounts/abcd1234-d1c0-4645-a699-abcd1234",
    "location": "West US",
    "name": "abcd1234-d1c0-4645-a699-abcd1234",
    "restorableLocations": [
      {
        "locationName": "West US"
      },
      {
        "locationName": "East US"
      }
    ]
  }
]

Use az cosmosdb mongodb restorable-database list to list all restorable versions of databases for live accounts:

az cosmosdb mongodb restorable-database list \
    --instance-id <instance-id-of-account> \
    --location <location>

Use az cosmosdb mongodb restorable-collection list to list all the versions of restorable collections within a specific database:

az cosmosdb mongodb restorable-collection list \
    --instance-id <instance-id-of-account> \
    --database-rid <owner-resource-id-of-database> \
    --location <location>

Initiate a restore operation for a deleted database by using az cosmosdb mongodb database restore:

az cosmosdb mongodb database restore \
     --resource-group <resource-group-name> \ 
     --account-name <account-name> \  
     --name <database-name> \
     --restore-timestamp <timestamp>

Initiate a restore operation for a deleted collection by using az cosmosdb mongodb collection restore:

az cosmosdb mongodb collection restore \
     --resource-group <resource-group-name> \ 
     --account-name <account-name> \   
     --database-name <database-name> \
    --name <container-name> \
     --restore-timestamp <timestamp>

Retrieve a list of all live and deleted restorable database accounts by using az cosmosdb restorable-database-account list:

az cosmosdb restorable-database-account list \
    --account-name <name-of-account>

[
  {
    "accountName": "deleted-account-1",
    "apiType": "Sql",
    "creationTime": "2020-08-02T22:23:00.095870+00:00",
    "deletionTime": "2020-08-02T22:26:13.483175+00:00",
    "id": "/subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.DocumentDB/locations/westus/restorableDatabaseAccounts/abcd1234-d1c0-4645-a699-abcd1234",
    "location": "West US",
    "name": "abcd1234-d1c0-4645-a699-abcd1234",
    "restorableLocations": [
      {
        "locationName": "West US"
      },
      {
        "locationName": "East US"
      }
    ]
  }
]

Use az cosmosdb gremlin restorable-database list to list all restorable versions of databases for live accounts:

az cosmosdb gremlin restorable-database list \
    --instance-id <instance-id-of-account> \
    --location <location>

Use az cosmosdb gremlin restorable-graph list to list all the versions of restorable graphs within a specific database:

az cosmosdb gremlin restorable-graph list \
    --instance-id <instance-id-of-account> \
    --database-rid <owner-resource-id-of-database> \
    --location <location>

Initiate a restore operation for a deleted database by using az cosmosdb gremlin database restore:

az cosmosdb gremlin database restore \
     --resource-group <resource-group-name> \ 
     --account-name <account-name> \  
     --name <database-name> \ 
    --restore-timestamp <timestamp>

Initiate a restore operation for a deleted graph by using az cosmosdb gremlin graph restore:

az cosmosdb gremlin database restore \
     --resource-group <resource-group-name> \ 
     --account-name <account-name> \  
     --database-name <database-name> \ 
     --name <graph-name> \ 
    --restore-timestamp <timestamp>

Retrieve a list of all live and deleted restorable database accounts by using az cosmosdb restorable-database-account list:

az cosmosdb restorable-database-account list \
    --account-name <name-of-account>

[
  {
    "accountName": "deleted-account-1",
    "apiType": "Sql",
    "creationTime": "2020-08-02T22:23:00.095870+00:00",
    "deletionTime": "2020-08-02T22:26:13.483175+00:00",
    "id": "/subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.DocumentDB/locations/westus/restorableDatabaseAccounts/abcd1234-d1c0-4645-a699-abcd1234",
    "location": "West US",
    "name": "abcd1234-d1c0-4645-a699-abcd1234",
    "restorableLocations": [
      {
        "locationName": "West US"
      },
      {
        "locationName": "East US"
      }
    ]
  }
]

Use az cosmosdb table restorable-table list to list all restorable versions of tables for live accounts:

az cosmosdb table restorable-table list \
    --instance-id <instance-id-of-account> \
    --location <location>

Initiate a restore operation for a deleted table by using az cosmosdb table restore:

az cosmosdb table restore \
     --resource-group <resource-group-name> \
     --account-name <account-name> \
     --table-name <table-name> \
     --restore-timestamp <timestamp>

Use Azure PowerShell to restore a deleted container or database. Child containers and databases are also restored.

Important

The Az.CosmosDB module for Azure PowerShell version 2.0.5-preview or later is required to access the in-account restore cmdlets. If you do not have the preview version installed, run Install-Module -Name Az.CosmosDB -RequiredVersion 2.0.5-preview -AllowPrerelease.

Retrieve a list of all live and deleted restorable database accounts by using the Get-AzCosmosDBRestorableDatabaseAccount cmdlet:

Get-AzCosmosDBRestorableDatabaseAccount

Id                        : /subscriptions/{subscriptionId}/providers/Microsoft.DocumentDB/locations/westus/restorableDatabaseAccounts/abcd1234-d1c0-4645-a699-abcd1234
DatabaseAccountInstanceId : abcd1234-d1c0-4645-a699-abcd1234
Location                  : West US
DatabaseAccountName       : deleted-account-1
CreationTime              : 8/2/2020 10:23:00 PM
DeletionTime              : 8/2/2020 10:26:13 PM
ApiType                   : Sql
RestorableLocations       : {West US, East US}

Note

The account has CreationTime or DeletionTime fields. These fields also exist for regions. These times allow you to choose the correct region and a valid time range to use when you restore a resource.

Use the Get-AzCosmosDBSqlRestorableDatabase cmdlet to list all restorable versions of databases for live accounts:
```
$parameters = @{
    DatabaseAccountInstanceId = "<instance-id-of-account>"
    Location = "<location>"
}
Get-AzCosmosDBSqlRestorableDatabase @parameters
```
Note

Listing all the restorable database deletion events allows you to choose the right database in a scenario where the actual time of existence is unknown. If the event feed contains the Delete operation type in its response, then it’s a deleted database and it can be restored within the same account. The restore timestamp can be set to any timestamp before the deletion timestamp and within the retention window.
Use the Get-AzCosmosDBSqlRestorableContainer cmdlet to list all the versions of restorable containers within a specific database:
```
$parameters = @{
    DatabaseAccountInstanceId = "<instance-id-of-account>"
    DatabaseRId = "<owner-resource-id-of-database>"
    Location = "<location>"
}
Get-AzCosmosDBSqlRestorableContainer @parameters    
```
Note

Listing all the restorable database deletion events allows you allows you to choose the right container in a scenario where the actual time of existence is unknown. If the event feed contains the Delete operation type in its response, then it’s a deleted container and it can be restored within the same account. The restore timestamp can be set to any timestamp before the deletion timestamp and within the retention window.

Initiate a restore operation for a deleted database by using the Restore-AzCosmosDBSqlDatabase cmdlet:

$parameters = @{
    ResourceGroupName = "<resource-group-name>"
    AccountName = "<account-name>"
    Name = "<database-name>"
    RestoreTimestampInUtc = "<timestamp>"
}
Restore-AzCosmosDBSqlDatabase @parameters

Initiate a restore operation for a deleted container by using the Restore-AzCosmosDBSqlContainer cmdlet:

$parameters = @{
    ResourceGroupName = "<resource-group-name>"
    AccountName = "<account-name>"
    DatabaseName = "<database-name>"
    Name = "<container-name>"
    RestoreTimestampInUtc = "<timestamp>"
}
Restore-AzCosmosDBSqlContainer @parameters

Retrieve a list of all live and deleted restorable database accounts by using the Get-AzCosmosDBRestorableDatabaseAccount cmdlet:

Get-AzCosmosDBRestorableDatabaseAccount

Id                        : /subscriptions/{subscriptionId}/providers/Microsoft.DocumentDB/locations/westus/restorableDatabaseAccounts/abcd1234-d1c0-4645-a699-abcd1234
DatabaseAccountInstanceId : abcd1234-d1c0-4645-a699-abcd1234
Location                  : West US
DatabaseAccountName       : deleted-account-1
CreationTime              : 8/2/2020 10:23:00 PM
DeletionTime              : 8/2/2020 10:26:13 PM
ApiType                   : Sql
RestorableLocations       : {West US, East US}

Note

Use Get-AzCosmosdbMongoDBRestorableDatabase to list all restorable versions of databases for live accounts:

$parameters = @{
    DatabaseAccountInstanceId = "<instance-id-of-account>"
    Location = "<location>"
}
Get-AzCosmosdbMongoDBRestorableDatabase @parameters

Use the Get-AzCosmosDBMongoDBRestorableCollection cmdlet to list all the versions of restorable collections within a specific database:

$parameters = @{
    DatabaseAccountInstanceId = "<instance-id-of-account>"
    DatabaseRId = "<owner-resource-id-of-database>"
    Location = "<location>"
}
Get-AzCosmosDBMongoDBRestorableCollection @parameters

Initiate a restore operation for a deleted database by using the Restore-AzCosmosDBMongoDBDatabase cmdlet:

$parameters = @{
    ResourceGroupName = "<resource-group-name>"
    AccountName = "<account-name>"
    Name = "<database-name>"
    RestoreTimestampInUtc = "<timestamp>"
}
Restore-AzCosmosDBMongoDBDatabase @parameters

Initiate a restore operation for a deleted collection by using the Restore-AzCosmosDBMongoDBCollection cmdlet:

$parameters = @{
    ResourceGroupName = "<resource-group-name>"
    AccountName = "<account-name>"
    DatabaseName = "<database-name>"
    Name = "<collection-name>"
    RestoreTimestampInUtc = "<timestamp>"
}
Restore-AzCosmosDBMongoDBCollection @parameters

Retrieve a list of all live and deleted restorable database accounts by using the Get-AzCosmosDBRestorableDatabaseAccount cmdlet:

Get-AzCosmosDBRestorableDatabaseAccount

Id                        : /subscriptions/{subscriptionId}/providers/Microsoft.DocumentDB/locations/westus/restorableDatabaseAccounts/abcd1234-d1c0-4645-a699-abcd1234
DatabaseAccountInstanceId : abcd1234-d1c0-4645-a699-abcd1234
Location                  : West US
DatabaseAccountName       : deleted-account-1
CreationTime              : 8/2/2020 10:23:00 PM
DeletionTime              : 8/2/2020 10:26:13 PM
ApiType                   : Sql
RestorableLocations       : {West US, East US}

Note

Use the Get-AzCosmosdbGremlinRestorableDatabase cmdlet to list all restorable versions of databases for live accounts:

$parameters = @{
    DatabaseAccountInstanceId = "<instance-id-of-account>"
    Location = "<location>"
}
Get-AzCosmosdbGremlinRestorableDatabase @parameters

Use the Get-AzCosmosdbGremlinRestorableGraph cmdlet to list all versions of restorable graphs that are in a specific database:

$parameters = @{
    DatabaseAccountInstanceId = "<instance-id-of-account>"
    DatabaseRId = "<owner-resource-id-of-database>"
    Location = "<location>"
}
Get-AzCosmosdbGremlinRestorableGraph @parameters

Initiate a restore operation for a deleted database by using the Restore-AzCosmosDBGremlinDatabase cmdlet:

$parameters = @{
    ResourceGroupName = "<resource-group-name>"
    AccountName = "<account-name>"
    Name = "<database-name>"
    RestoreTimestampInUtc = "<timestamp>"
}
Restore-AzCosmosDBGremlinDatabase @parameters

Initiate a restore operation for a deleted graph by using the Restore-AzCosmosDBGremlinGraph cmdlet:

$parameters = @{
    ResourceGroupName = "<resource-group-name>"
    AccountName = "<account-name>"
    DatabaseName = "<database-name>"
    Name = "<graph-name>"
    RestoreTimestampInUtc = "<timestamp>"
}
Restore-AzCosmosDBGremlinGraph @parameters

Retrieve a list of all live and deleted restorable database accounts by using the Get-AzCosmosDBRestorableDatabaseAccount cmdlet:

Get-AzCosmosDBRestorableDatabaseAccount

Id                        : /subscriptions/{subscriptionId}/providers/Microsoft.DocumentDB/locations/westus/restorableDatabaseAccounts/abcd1234-d1c0-4645-a699-abcd1234
DatabaseAccountInstanceId : abcd1234-d1c0-4645-a699-abcd1234
Location                  : West US
DatabaseAccountName       : deleted-account-1
CreationTime              : 8/2/2020 10:23:00 PM
DeletionTime              : 8/2/2020 10:26:13 PM
ApiType                   : Sql
RestorableLocations       : {West US, East US}

Note

Use the Get-AzCosmosdbTableRestorableTable cmdlet to list all restorable versions of tables for live accounts:

$parameters = @{
    DatabaseAccountInstanceId = "<instance-id-of-account>"
    Location = "<location>"
}
Get-AzCosmosdbTableRestorableTable @parameters

Initiate a restore operation for a deleted table by using the Restore-AzCosmosDBTable cmdlet:

$parameters = @{
    ResourceGroupName = "<resource-group-name>"
    AccountName = "<account-name>"
    Name = "<table-name>"
    RestoreTimestampInUtc = "<timestamp>"
}
Restore-AzCosmosDBTable @parameters

You can restore deleted containers and databases by using an Azure Resource Manager template.

Create or locate an Azure Cosmos DB resource in your template. Here's a generic example of a resource:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "resources": [
    {
      "name": "msdocs-example-arm",
      "type": "Microsoft.DocumentDB/databaseAccounts",
      "apiVersion": "2022-02-15-preview",
      "location": "West US",
      "properties": {
        "locations": [
          {
            "locationName": "West US"
          }
        ],
        "backupPolicy": {
          "type": "Continuous"
        },
        "databaseAccountOfferType": "Standard"
      }
    }
  ]
}

To update the Azure Cosmos DB resource in your template:

Set properties.createMode to restore.
Define a properties.restoreParameters object.
Set properties.restoreParameters.restoreTimestampInUtc to a UTC time stamp.
Set properties.restoreParameters.restoreSource to the instance identifier of the account that is the source of the restore operation.

{
  "properties": {
    "name": "<name-of-database-or-container>",
    "restoreParameters": {
      "restoreSource": "<source-account-instance-id>",
      "restoreTimestampInUtc": "<timestamp>"
    },
    "createMode": "Restore"
  }
}

{
  "properties": {
    "name": "<name-of-database-or-collection>",
    "restoreParameters": {
      "restoreSource": "<source-account-instance-id>",
      "restoreTimestampInUtc": "<timestamp>"
    },
    "createMode": "Restore"
  }
}

{
  "properties": {
    "name": "<name-of-database-or-graph>",
    "restoreParameters": {
      "restoreSource": "<source-account-instance-id>",
      "restoreTimestampInUtc": "<timestamp>"
    },
    "createMode": "Restore"
  }
}

{
  "properties": {
    "name": "<name-of-table>",
    "restoreParameters": {
      "restoreSource": "<source-account-instance-id>",
      "restoreTimestampInUtc": "<timestamp>"
    },
    "createMode": "Restore"
  }
}

Note

Use az cosmosdb restorable-database-account list to retrieve a list of instance identifiers for all live and deleted restorable database accounts.

Deploy the template by using az deployment group create:

az deployment group create \
    --resource-group <resource-group-name> \
    --template-file <template-filename>

Track the status of a restore operation

When a point-in-time restore is initiated for a deleted container or database, the operation is identified as an InAccount restore operation on the resource.

To get a list of restore operations for a specific resource, filter the activity log of the account by using the InAccount Restore Deleted search filter and a time filter. The list that's returns includes the UserPrincipalName field, which identifies the user who initiated the restore operation. For more information about how to access activity logs, see Audit point-in-time restore actions.

Next steps

Enable continuous backup by using the Azure portal, Azure PowerShell, the Azure CLI, or Azure Resource Manager.
Learn how to migrate an account from periodic backup to continuous backup.
Review the continuous backup mode resource model.
Manage the permissions that are required to restore data by using continuous backup mode.

Restore a deleted container or database to the same Azure Cosmos DB account (preview)

Prerequisites

Restore a deleted container or database

Track the status of a restore operation

Next steps

Feedback

Additional resources

Additional resources