Migrate to Tigris from S3/GCS/Azure

Prerequisites

tigris help || npm install -g @tigrisdata/cli

@tigrisdata/cli

Migration Strategies

Shadow Bucket (Recommended)

# Create a Tigris bucket that shadows your S3 bucket
tigris buckets create my-app-uploads \
  --shadow-source s3://my-existing-s3-bucket \
  --shadow-region us-east-1 \
  --shadow-access-key AKIA_YOUR_AWS_KEY \
  --shadow-secret-key YOUR_AWS_SECRET

1. Requests go to Tigris
2. If the object exists in Tigris, it's served directly
3. If not, Tigris fetches it from S3, serves it, and caches it
4. Over time, all frequently accessed objects migrate automatically
5. Background backfill copies remaining objects

# Verify object counts match
tigris ls t3://my-app-uploads --recursive | wc -l
aws s3 ls s3://my-existing-s3-bucket --recursive | wc -l

# Remove shadow source (makes Tigris the sole source)
tigris buckets update my-app-uploads --remove-shadow

Bulk Copy

# Copy all objects from S3 to Tigris
tigris cp s3://my-existing-bucket t3://my-app-uploads -r

# Or use AWS CLI pointed at Tigris
AWS_ENDPOINT_URL_S3=https://t3.storage.dev \
AWS_ACCESS_KEY_ID=tid_xxx \
AWS_SECRET_ACCESS_KEY=tsec_yyy \
aws s3 sync s3://my-existing-bucket s3://my-app-uploads

From Google Cloud Storage

gsutil -m cp -r gs://my-gcs-bucket /tmp/migration/
tigris cp /tmp/migration/ t3://my-app-uploads/ -r

From Azure Blob Storage

az storage blob download-batch -d /tmp/migration/ -s my-container
tigris cp /tmp/migration/ t3://my-app-uploads/ -r

SDK Code Changes

• Node.js / TypeScript — Read

  ./resources/sdk-nodejs.md

  for AWS SDK → Tigris SDK migration
• Go — Read

  ./resources/sdk-go.md

  for AWS SDK → Tigris SDK migration
• Python — Read

  ./resources/sdk-python.md

  for boto3 → tigris-boto3-ext migration
• Ruby — Read

  ./resources/sdk-ruby.md

  for aws-sdk-s3 endpoint swap
• PHP — Read

  ./resources/sdk-php.md

  for aws-sdk-php endpoint swap

Environment Variable Changes

# Before (AWS)
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=...
AWS_REGION=us-east-1
S3_BUCKET=my-bucket

# After (Tigris)
AWS_ACCESS_KEY_ID=tid_xxx
AWS_SECRET_ACCESS_KEY=tsec_yyy
AWS_ENDPOINT_URL_S3=https://t3.storage.dev
AWS_REGION=auto
S3_BUCKET=my-bucket  # bucket name can stay the same

TIGRIS_STORAGE_ACCESS_KEY_ID=tid_xxx
TIGRIS_STORAGE_SECRET_ACCESS_KEY=tsec_yyy
TIGRIS_STORAGE_ENDPOINT=https://t3.storage.dev
TIGRIS_STORAGE_BUCKET=my-bucket

Verification Checklist

• Object count matches between source and Tigris
• Spot-check files: download a few and verify content/checksums
• Test presigned URL generation (endpoint must point to Tigris)
• Test CORS if using browser uploads (reconfigure on Tigris bucket)
• Test all upload/download code paths in staging
• Update CDN origin if using CloudFront/similar (point to Tigris)
• Update DNS if using custom domains

Rollback Strategy

1. Keep source bucket read-only during migration (don't delete data)
2. Run both systems in parallel during verification
3. Only delete source data after confirming Tigris works fully
4. If using shadow bucket, removing the shadow source is the point of no return

Common Mistakes

tigris buckets cors set

us-east-1

auto

path_style

force_path_style: true

use_path_style_endpoint: true

Related Skills

• file-storage — CLI setup and SDK reference
• tigris-security-access-control — CORS and access key setup

Official Documentation

• S3 Compatibility: https://www.tigrisdata.com/docs/sdks/s3/
• Shadow Buckets: https://www.tigrisdata.com/docs/