Edit

Share via

Migrate an Azure Cosmos DB account from periodic to continuous backup mode

  • Applies to: ✅ NoSQL, ✅ MongoDB, ✅ Apache Gremlin, ✅ Table

Azure Cosmos DB accounts with periodic mode backup policy can be migrated to continuous mode using the Azure portal, Azure CLI, Azure PowerShell, or Bicep templates. Migration from periodic to continuous mode is one-way and isn't reversible. After you migrate from periodic to continuous mode, you get the benefits of continuous mode.

Key reasons to migrate to continuous mode:

  • Restore data yourself using Azure portal, CLI, or PowerShell.
  • Restore to a specific second within the last 30-day or 7-day window.
  • Make sure backups are consistent across shards or partition key ranges.
  • Restore a container, database, or the full account after deletion or changes.
  • Select events on the container, database, or account and choose when to start the restore.

Note

Migration is one-way and can't be reversed. Once you migrate from periodic mode to continuous mode, you can't switch back.

You can migrate an account to continuous backup mode only if these conditions are true. Also, check the point in time restore limitations before you migrate:

  • The account is API for NoSQL, Table, Gremlin, or MongoDB.
  • The account never had Azure Synapse Link disabled for a container.

If the account uses customer-managed keys, declare a managed identity (system-assigned or user-assigned) in the Key Vault access policy and set it as the default identity on the account.

Important

After you migrate your account to continuous backup mode, the cost can change compared to periodic backup mode. The choice between 30 days and seven days also affects backup cost. For details, see continuous backup mode pricing.

Prerequisites

  • An Azure Cosmos DB account
  • The Microsoft.DocumentDB/databaseAccounts/write role-based access control permission for the account that is being migrated
  • Latest version of Azure CLI or Azure PowerShell

Migrate using portal

Use the following steps to migrate your account from periodic backup to continuous backup mode:

  1. Sign in to the Azure CLI.

    az login

  2. Migrate the account to continuous30days or continuous7days tier.

    az cosmosdb update \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --backup-policy-type "Continuous"

    az cosmosdb update \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --backup-policy-type "Continuous" \
    --continuous-tier "Continuous7Days"

    Note

    If you don't provide a tier value, the default is continuous30days.

  3. After the migration completes successfully, the output shows the backupPolicy object, which includes type property with a value of Continuous.

    {
  ...
  "backupPolicy": {
    "continuousModeProperties": {
      "tier": "Continuous7Days"
    },
    "migrationState": null,
    "type": "Continuous"
  },
  ...
}

Check the migration status

Use the Azure CLI to check the status of an existing migration.

  1. Run the following command to get the properties of the Azure Cosmos DB account.

    az cosmosdb show \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \

  2. Check the status and targetType properties of the backupPolicy object. The status should be InProgress after the migration starts.

    {
  ...
  "backupPolicy": {
    ...
    "migrationState": {
      "status": "InProgress",
      "targetType": "Continuous"
    },
    "type": "Periodic"
  },
  ...
}

  3. When the migration is complete, the backup type changes to Continuous and includes the chosen tier. If a tier wasn't provided, the tier would be set to Continuous30Days. Run the same az cosmosdb show command again to check the status.

    {
  ...
  "backupPolicy": {
    "continuousModeProperties": {
      "tier": "Continuous7Days"
    },
    "migrationState": null,
    "type": "Continuous"
  },
  ...
}

Change Continuous Mode tiers

You can switch between Continuous30Days and Continous7Days in Azure PowerShell, Azure CLI, or the Azure portal.

The Following Azure CLI command illustrates switching an existing account to Continous7Days:

az cosmosdb update \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --backup-policy-type "Continuous" \
    --continuous-tier "Continuous7Days"

You can also use an ARM template in a method similar to using the Azure CLI and Azure PowerShell.

Note

When you switch from the 30-day to the 7-day tier, you immediately lose the ability to restore data older than seven days. When you switch from the 7-day to the 30-day tier, you can only restore data from the last seven days until new backups accumulate. You can check the earliest available restore time using Azure PowerShell or Azure CLI. Any price changes from switching tiers take effect immediately.

Migrate to continuous backup using Bicep

To migrate to continuous backup mode using a Bicep template and Azure Resource Manager, find the backupPolicy section of your template and update the type property.

  1. Consider this example template that has a Periodic backup policy:

    resource azureCosmosDBAccount 'Microsoft.DocumentDB/databaseAccounts@2025-04-15' = {
  name: '<account-name>'
  properties: {
    // Other required properties omitted for brevity
    backupPolicy: {
      type: 'Periodic'
      periodicModeProperties: {
        backupIntervalInMinutes: 240 // 4 hours
        backupRetentionIntervalInHours: 48 // 2 days
      }
    }
  }
}

  2. Update the example template to use Continuous backup mode at the 7-day tier:

    resource azureCosmosDBAccount 'Microsoft.DocumentDB/databaseAccounts@2025-04-15' = {
  name: '<account-name>'
  properties: {
    // Other required properties omitted for brevity
    backupPolicy: {
      type: 'Continuous'
      continuousModeProperties: {
        tier: 'Continuous7Days'
      }
    }
  }
}

  3. Deploy the template by using Azure PowerShell or CLI. The following example shows how to deploy the template with a CLI command:

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

Related content