Replicating to Tigris (Fly.io)

This guide will show you how to use Tigris as a database replica path for Litestream. Tigris is Fly.io’s globally distributed S3-compatible object storage. You will need a Fly.io account to complete this guide.

v0.5.0 Litestream automatically detects Tigris endpoints and configures the required settings for you.

Setup#

Install the Fly CLI#

If you haven’t already, install the Fly CLI by following the installation instructions. Once installed, authenticate with your account:

fly auth login

Create a Tigris bucket#

Use the Fly CLI to create a new storage bucket:

fly storage create

You’ll be prompted to choose a name for your bucket. After creation, Fly.io will display your credentials:

Your project (my-bucket) is ready.

Set the following secrets on your app:
AWS_ACCESS_KEY_ID=tid_xxxxxxxxxxxxxxxxxxxx
AWS_SECRET_ACCESS_KEY=tsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
AWS_ENDPOINT_URL_S3=https://fly.storage.tigris.dev
AWS_REGION=auto
BUCKET_NAME=my-bucket

Save these values for use in your Litestream configuration.

Usage#

Command line usage#

You can replicate to Tigris from the command line by setting environment variables with the credentials from bucket creation:

export AWS_ACCESS_KEY_ID=tid_xxxxxxxxxxxxxxxxxxxx
export AWS_SECRET_ACCESS_KEY=tsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Then specify your bucket with the Tigris endpoint as a replica URL:

litestream replicate /path/to/db s3://BUCKETNAME?endpoint=fly.storage.tigris.dev&region=auto

You can later restore your database from Tigris to a local my.db path:

litestream restore -o my.db s3://BUCKETNAME?endpoint=fly.storage.tigris.dev&region=auto

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:

access-key-id: tid_xxxxxxxxxxxxxxxxxxxx
secret-access-key: tsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

dbs:
  - path: /path/to/local/db
    replica:
      url: s3://BUCKETNAME?endpoint=fly.storage.tigris.dev&region=auto

Or you can expand your configuration into multiple fields:

dbs:
  - path: /path/to/local/db
    replica:
      type: s3
      bucket: BUCKETNAME
      path:   db
      endpoint: fly.storage.tigris.dev
      region: auto

You may also specify your credentials on a per-replica basis:

dbs:
  - path: /path/to/local/db
    replica:
      type: s3
      bucket: BUCKETNAME
      path:   db
      endpoint: fly.storage.tigris.dev
      region: auto
      access-key-id: tid_xxxxxxxxxxxxxxxxxxxx
      secret-access-key: tsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Auto-Detection#

When Litestream detects a Tigris endpoint (fly.storage.tigris.dev), it automatically applies Tigris-specific settings:

• sign-payload: true — Required by Tigris for request authentication
• require-content-md5: false — Tigris doesn’t support Content-MD5 headers on DELETE operations

These settings are applied automatically. You only need to override them if you have specific requirements.

Manual Override#

If you need to override the auto-detected settings, you can specify them explicitly in your configuration:

dbs:
  - path: /path/to/local/db
    replica:
      type: s3
      bucket: BUCKETNAME
      path:   db
      endpoint: fly.storage.tigris.dev
      region: auto
      sign-payload: true
      require-content-md5: false

Environment Variables#

Litestream supports standard AWS environment variables for Tigris credentials:

You can also use the Litestream-specific environment variables:

Running on Fly.io#

When deploying your application on Fly.io with Litestream, you can attach the Tigris bucket directly to your app. The credentials will be automatically injected as secrets:

fly storage create --app my-app

Then configure Litestream to use these environment variables in your litestream.yml:

dbs:
  - path: /data/myapp.db
    replica:
      url: s3://${BUCKET_NAME}?endpoint=fly.storage.tigris.dev&region=auto

Global Distribution#

Tigris automatically stores objects in the region where they’re written. When requested from other regions, objects are cached close to the requesting user. This provides CDN-like behavior without additional configuration, which is beneficial for distributed applications using Litestream for database replication.