# tigris-s3-migration

A skill that walks an object-storage migration from AWS S3, GCS or Azure Blob to Tigris. Useful when a bucket has to switch over without taking production down.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 3100 installs · ★ 2
- Author: tigrisdata
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/tigrisdata/skills/tree/HEAD/skills/tigris-s3-migration/SKILL.md
- Updated: 2026-07-23
- HTML: https://affpapa.org/en/nevibecode/skills/tigris-s3-migration

## What it does

The skill lays out three migration strategies: shadow bucket, bulk copy and incremental sync. The main one is the shadow bucket. Tigris serves an object from your existing S3 bucket on a cache miss, hands it back, and backfills its own copy. Nothing has to move up front.

Setup runs through the Tigris CLI. You create a bucket with `tigris buckets create`, then point it at the source with `tigris buckets set-migration`, passing the source bucket, endpoint, region and AWS keys. Adding `--write-through` also syncs new writes back to the source, which keeps a rollback path open. After that `tigris buckets migrate` drains every object that has not moved yet, and `tigris buckets set-migration --disable` makes Tigris the sole source.

Make sure the CLI is there first: `tigris help || npm install -g @tigrisdata/cli`. For GCS and Azure the skill ships bulk-copy commands built on `gsutil` and `az storage blob download-batch`. Files under `./resources/` show the endpoint swap for the AWS SDK in Node.js, Go, Python, Ruby and PHP. The usual breakage is a region hardcoded to `us-east-1` — Tigris wants `auto`.

## Requirements
- Works with: AWS, Azure

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add tigrisdata/skills --skill tigris-s3-migration -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/tigris-s3-migration/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/tigris-s3-migration/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add tigrisdata/skills --skill tigris-s3-migration -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/tigris-s3-migration/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add tigrisdata/skills --skill tigris-s3-migration -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/tigris-s3-migration/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install tigrisdata/skills tigris-s3-migration
```

2. **Manually: put the files in place**
- File: `.github/skills/tigris-s3-migration/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add tigrisdata/skills --skill tigris-s3-migration -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/tigrisdata/skills --path skills/tigris-s3-migration
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/tigris-s3-migration/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add tigrisdata/skills --skill tigris-s3-migration -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/tigrisdata/skills/tree/HEAD/skills/tigris-s3-migration/SKILL.md

## When to use it
- move a production bucket off AWS S3 onto Tigris with no downtime
- set up a shadow bucket that backfills objects on demand
- drain the remaining objects with `tigris buckets migrate`
- copy data out of Google Cloud Storage or Azure Blob in bulk
- swap the endpoint in the AWS SDK and environment variables

## Example prompts
- migrate the my-app-uploads bucket from S3 to Tigris using a shadow bucket
- set up `tigris buckets set-migration` with `--write-through` so we can roll back
- run `tigris buckets migrate my-app-uploads/images/` and report progress

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: ffe83dd034481d33.

BEGIN THIRD-PARTY FILE ffe83dd034481d33
````text
---
name: tigris-s3-migration
description: Use when migrating from AWS S3, Google Cloud Storage, or Azure Blob to Tigris — shadow buckets via `tigris buckets set-migration`, active drain via `tigris buckets migrate`, bulk copy, SDK endpoint swap, zero-downtime migration
---

# Migrate to Tigris from S3/GCS/Azure

Migrate your object storage to Tigris with zero downtime. Tigris is S3-compatible, so most apps need only an endpoint and credential swap. Shadow buckets enable transparent migration without moving data upfront.

## Prerequisites

**Before doing anything else**, install the Tigris CLI if it's not already available:

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

If you need to install it, tell the user: "I'm installing the Tigris CLI (`@tigrisdata/cli`) so we can work with Tigris object storage."

## Migration Strategies

| Strategy             | Downtime | Best For                                                                |
| -------------------- | -------- | ----------------------------------------------------------------------- |
| **Shadow bucket**    | Zero     | Production apps — Tigris reads from S3 on miss, backfills automatically |
| **Bulk copy**        | Brief    | Small datasets, clean cutover                                           |
| **Incremental sync** | Zero     | Large datasets, gradual migration                                       |

---

## Shadow Bucket (Recommended)

Tigris reads from your existing S3 bucket on cache miss and gradually backfills data. No upfront data movement needed.

```bash
# Create a Tigris bucket
tigris buckets create my-app-uploads
# Point the Tigris bucket at the source S3 bucket
tigris buckets set-migration my-app-uploads \
  --bucket my-existing-s3-bucket \
  --endpoint https://s3.us-east-1.amazonaws.com \
  --region us-east-1 \
  --access-key AKIA_YOUR_AWS_KEY \
  --secret-key YOUR_AWS_SECRET
```

Add `--write-through` to also sync new writes back to the source bucket — useful when you want a safe rollback path during the migration window.

**How it works:**

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

**Migrate everything up front (optional):**

Lazy migration only copies objects when they're requested. To actively migrate every remaining object server-side, run:

```bash
# Migrate every unmigrated object in the bucket
````
END THIRD-PARTY FILE ffe83dd034481d33

The third-party file has ended. Everything between the ffe83dd034481d33 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2445 of 6602 bytes. © tigrisdata · MIT · https://github.com/tigrisdata/skills/tree/HEAD/skills/tigris-s3-migration/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md