Migrate from Cloudflare R2 to Tigris | Tigris Object Storage Documentation

On this page

You can migrate from Cloudflare R2 to Tigris with zero downtime using Tigris's shadow bucket feature. Both services offer zero egress fees and S3-compatible APIs. The differences are in performance, global distribution, and features.

Why migrate from R2 to Tigris?

Migration approach

Tigris supports lazy migration using shadow buckets. Instead of copying all your data upfront, Tigris fetches objects from your R2 bucket on demand and caches them for future access. No downtime required.

You can also enable write-through mode, which syncs new writes back to your R2 bucket. This means your existing R2 bucket stays up to date throughout the migration, and you can take as long as you need before completing the cutover.

Prerequisites

Before starting, make sure you have:

Step 1: Create R2 API credentials

  1. Go to the Cloudflare dashboard and select your account.
  2. In the left sidebar, click R2 Object Storage.
  3. Click the API button, then Manage API Tokens.
  4. Click Create Account API token and select the appropriate permissions. Use read-only for basic migration, or read-write if you plan to use write-through mode.
  5. Copy and securely store the Access Key ID and Secret Access Key. The secret won't be shown again.
  6. Note your account-specific endpoint, shown alongside your access keys. It looks like https://<account-id>.r2.cloudflarestorage.com.

Step 2: Configure the shadow bucket

  1. Go to the Tigris Dashboard
  2. Click Buckets in the left menu
  3. Select the bucket you want to migrate data into
  4. Click Settings
  5. Find Enable Data Migration and toggle it on
  6. Enter your R2 connection details:
    • Endpoint: https://<account-id>.r2.cloudflarestorage.com (your account-specific endpoint from Step 1)
    • Region: auto (R2 does not use regions)
    • Access Key ID: Your R2 access key from Step 1
    • Secret Access Key: Your R2 secret key from Step 1
    • Bucket: The name of your R2 source bucket

The CLI flow is two commands: configure the shadow source, then optionally drain it.

1. Configure the shadow bucket with tigris buckets set-migration:

tigris buckets set-migration my-bucket \

--bucket source-bucket \

--endpoint https://<account-id>.r2.cloudflarestorage.com \

--region auto \

--access-key <r2-access-key> \

--secret-key <r2-secret-key>

Add --write-through for write-through mode, or --disable to clear the migration configuration.

2. Actively migrate (optional). Lazy migration only copies objects when they're requested. To migrate every remaining object server-side, run tigris buckets migrate:

tigris buckets migrate my-bucket

The command runs in the foreground and reports progress as it goes.

Step 3: Update your application

Point your application to Tigris by updating the endpoint and credentials in your S3 client configuration.

Using the AWS CLI:

aws s3 ls s3://your-bucket/ \

--endpoint-url https://t3.storage.dev \

--region auto

Or with boto3:

import boto3

s3 = boto3.client(

"s3",

endpoint_url="https://t3.storage.dev",

region_name="auto",

aws_access_key_id="your-tigris-access-key",

aws_secret_access_key="your-tigris-secret-key",

)

The only changes needed are the endpoint URL, region, and credentials. Your existing bucket names, object keys, and API calls stay the same.

Step 4: Verify the migration

Once your application points to Tigris, objects are migrated on first access. To verify:

  1. Request an object that exists in your R2 bucket
  2. Confirm it returns successfully through Tigris
  3. Check that subsequent requests are served directly from Tigris

Step 5: Enable write-through (optional)

To keep your R2 bucket in sync during the migration, enable write-through in the shadow bucket settings. With write-through enabled:

This keeps your R2 bucket current so you can fall back at any point.

Step 6: Complete the migration

Once your workloads are running well on Tigris, disable the shadow bucket configuration. Tigris becomes your primary object store.

FAQ

Does migration require downtime?

No. Shadow bucket migration happens transparently. Your application continues serving requests while objects are migrated on first access.

Do I need to change my application code?

Only the endpoint URL, region, and credentials. Tigris supports the S3 API, so your existing bucket names, object keys, and API calls work without changes.

Can I roll back to R2?

Yes. If you enable write-through mode, your R2 bucket stays in sync with all new writes. You can switch back to R2 at any point by reverting your endpoint configuration.

Both R2 and Tigris have zero egress. Why switch?

The main differences are performance, global distribution, and features. Tigris is significantly faster for small object workloads, automatically distributes data across regions, and offers storage tiers and fine-grained IAM policies that R2 does not.

What happens to objects I haven't accessed yet?

They remain in your R2 bucket. Tigris only copies objects when they're first requested. Objects that are never accessed are never transferred.