Replicating to Alibaba Cloud OSS

v0.5.0 This guide will show you how to use Litestream’s native Alibaba Cloud OSS support to replicate your database. You will need an Alibaba Cloud account to complete this guide.

Setup#

Create a bucket#

In the OSS Console, click the “Create Bucket” button. Enter a unique bucket name and select your preferred region (e.g., cn-hangzhou, us-west-1). Remember your bucket name and region as you’ll need those later.

Create access credentials#

From the RAM Console, navigate to “AccessKey Management” under your account. Click “Create AccessKey” to generate a new key pair. You will need to save the “AccessKey ID” and “AccessKey Secret” for later use in this guide.

Usage#

Command line usage#

You can replicate to Alibaba Cloud OSS from the command line by setting your credentials via environment variables:

export OSS_ACCESS_KEY_ID=xxxxxxxxxxxxxxxx
export OSS_ACCESS_KEY_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

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

litestream replicate /path/to/db oss://BUCKET.oss-REGION.aliyuncs.com/PATH

You can later restore your database from Alibaba Cloud OSS to a local my.db path with the following command.

litestream restore -o my.db oss://BUCKET.oss-REGION.aliyuncs.com/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: oss://BUCKET.oss-REGION.aliyuncs.com/PATH
      access-key-id: xxxxxxxxxxxxxxxx
      secret-access-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Or you can expand your configuration into multiple fields:

dbs:
  - path: /path/to/local/db
    replica:
      type:   oss
      bucket: BUCKET
      region: REGION
      path:   PATH

You can also use the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables instead of specifying the credentials in your configuration file.

Advanced Options#

Alibaba Cloud OSS replicas support additional configuration options for multipart uploads:

dbs:
  - path: /path/to/local/db
    replica:
      type:        oss
      bucket:      BUCKET
      region:      REGION
      path:        PATH
      part-size:   10485760  # 10MB part size for multipart uploads
      concurrency: 5         # Number of parallel upload workers