Migrate to Tigris Object Storage | Tigris Object Storage Documentation

On this page

Tigris supports zero-downtime migration from any S3-compatible storage provider using shadow buckets. Data is migrated lazily as it's accessed, so there's no need for a large upfront data transfer. With write-through mode enabled, new writes are synced back to your old bucket, so you can take as long as you need to complete the migration.

Provider-specific guides

How shadow bucket migration works

Once you've specified your shadow bucket (the source S3-compatible bucket), Tigris handles requests so that data is gradually migrated as it is accessed.

This approach works well for large-scale migrations where copying all data at once would be slow or expensive. Instead of migrating everything up front, Tigris fetches objects from the shadow bucket only when requested and copies them into your Tigris bucket asynchronously. Only actively used data is migrated, reducing both latency and cost.

Write-through mode: migrate at your own pace

Most migration tools force a hard cutover: you copy your data, switch over, and hope nothing breaks. Tigris takes a different approach.

With the optional write-through setting enabled, Tigris syncs all new writes back to your original bucket. Your old bucket stays up to date with every new object, update, and delete. This means you can run on Tigris in production while keeping your previous storage provider fully current.

There's no deadline to finish the migration. You can run in write-through mode for days, weeks, or months while you verify that everything works. If you need to roll back, your old bucket has all the latest data. When you're ready, turn off write-through and decommission the old bucket.

Under the hood:

Note: Object listing behavior depends on whether write-through mode is enabled. When write-through is enabled, the list API returns the full contents of the shadow bucket. When write-through is disabled, the list API only includes objects that have already been migrated into Tigris; objects that exist solely in the shadow bucket are not listed until they are accessed and migrated.

Enable Data Migration

Configure the shadow bucket from the Tigris Dashboard or the CLI. See the provider-specific guides above for the exact endpoint, region, and credential format for your source.

To enable data migration from any S3-compatible bucket:

If the storage service does not require a region, set the region to auto. For example, GCS and Cloudflare R2 use auto.

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://<source-endpoint> \
  --region <source-region> \
  --access-key <key> \
  --secret-key <secret>

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

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

# Migrate every unmigrated object in the bucket
tigris buckets migrate my-bucket

# Migrate only objects under a key prefix
tigris buckets migrate my-bucket/images/

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

Copying object ACLs

By default, migrated objects inherit the access control settings of the bucket to which they are migrated. However, if the bucket is configured to allow object ACLs, the migration process will copy object ACLs from the shadow bucket to the Tigris bucket. The following rules apply: