Replicating to Azure Blob Storage

This guide will show you how to use Litestream to replicate to an Azure Blob Storage container. You will need an Azure account and to complete this guide.

Setup#

Create a container#

In the Azure Portal, use the top search bar to navigate to “Storage Accounts”. If you do not have a storage account, click the “New” button, enter your storage account name, and click “Review + create”.

Once you have a storage account, select it from the list of accounts and navigate to the Containers subsection. Click the "+" button to create a new container. Remember your storage account name and your container name as you’ll need those later.

Create an access key#

From your storage account, navigate to the Access Keys subsection. You’ll see two access keys already exist. Click the “Show keys” button to reveal them. Copy the value of one of the “Key” textboxes. This will be be your account key.

Usage#

Command line usage#

You can replicate to Azure Blob Storage from the command line by setting your account key via an environment variable:

export LITESTREAM_AZURE_ACCOUNT_KEY=...

You can then specify your replica as a replica URL on the command line. For example, you can replicate a database to your container with the following command. Replace the placeholders for your account, container, & path.

litestream replicate /path/to/db abs://STORAGEACCOUNT@CONTAINERNAME/PATH

You can later restore your database from Azure Blob Storage to a local my.db path with the following command.

litestream restore -o my.db abs://STORAGEACCOUNT@CONTAINERNAME/PATH

Configuration file usage#

Litestream is typically run as a background service which uses a configuration file. You can configure a replica for your database using the url format.

dbs:
  - path: /path/to/local/db
    replica:
      url: abs://STORAGEACCOUNT@CONTAINERNAME/PATH
      account-key:  ACCOUNTKEY

Or you can expand your configuration into multiple fields:

dbs:
  - path: /path/to/local/db
    replica:
      type: abs
      account-name: STORAGEACCOUNT
      account-key:  ACCOUNTKEY
      bucket:       CONTAINERNAME
      path:         PATH

You can also use the LITESTREAM_AZURE_ACCOUNT_KEY environment variable instead of specifying the account key in your configuration file.

v0.5.0 Litestream v0.5.0+ uses Azure SDK v2, which maintains compatibility with existing authentication methods and adds support for Azure’s default credential chain including Managed Identity. See the Azure SDK v2 Migration Guide for details on new authentication options.

Authentication Methods#

Shared Key (Account Key)#

The simplest authentication method uses your storage account key:

dbs:
  - path: /path/to/local/db
    replica:
      type: abs
      account-name: STORAGEACCOUNT
      account-key: ACCOUNTKEY
      bucket: CONTAINERNAME
      path: PATH

Or via environment variable:

export LITESTREAM_AZURE_ACCOUNT_KEY=your-account-key

Managed Identity (Azure Infrastructure)#

v0.5.0 When running on Azure infrastructure (VMs, App Service, Container Apps, AKS), you can use Managed Identity without any credentials:

dbs:
  - path: /path/to/local/db
    replica:
      type: abs
      account-name: STORAGEACCOUNT
      bucket: CONTAINERNAME
      path: PATH
      # No account-key needed - uses Managed Identity

Ensure your Azure resource has a Managed Identity enabled and has the appropriate role assignment (e.g., “Storage Blob Data Contributor”) on the storage account.

Service Principal#

v0.5.0 For non-Azure environments or when Managed Identity isn’t suitable, use a service principal via environment variables:

export AZURE_CLIENT_ID=your-app-id
export AZURE_TENANT_ID=your-tenant-id
export AZURE_CLIENT_SECRET=your-client-secret

dbs:
  - path: /path/to/local/db
    replica:
      type: abs
      account-name: STORAGEACCOUNT
      bucket: CONTAINERNAME
      path: PATH

Azure CLI (Local Development)#

v0.5.0 For local development, authenticate using the Azure CLI:

az login

Litestream will automatically use your Azure CLI credentials when no other authentication method is configured.

See Also#

• Azure SDK v2 Migration - Upgrading authentication
• Troubleshooting - Common issues and solutions
• Configuration Reference - Complete configuration options