tigris-snapshots-recovery

name	tigris-snapshots-recovery
description	Use when recovering deleted or changed files from Tigris, restoring objects to a previous state, or setting up snapshot-enabled buckets for point-in-time recovery

Tigris Snapshots & Point-in-Time Recovery

Recover deleted or changed files from any point in time. Tigris snapshot-enabled buckets automatically track every change — you can restore files without having explicitly taken a snapshot.

Prerequisites

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

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."

Key Facts

• Snapshots must be enabled at bucket creation time. You cannot enable snapshots on an existing bucket. You must create a new bucket with snapshots enabled.
• Every change is tracked automatically. Even without explicitly taking a snapshot, every put, delete, and overwrite is preserved. You can recover any object from any point in time.
• Explicit snapshots are optional bookmarks. Taking a named snapshot just marks a point in time for easy reference. The data is already preserved regardless.
• Snapshot buckets must use STANDARD storage tier. Lifecycle transitions and TTL are not supported on snapshot-enabled buckets.

---

Create a Snapshot-Enabled Bucket

# New bucket with snapshots enabled
tigris buckets create my-bucket --snapshot

# ⚠ This will NOT work — cannot enable snapshots on existing bucket
# tigris buckets update my-bucket --snapshot  ← NOT SUPPORTED

import { createBucket } from "@tigrisdata/storage";

const result = await createBucket("my-bucket", {
  enableSnapshot: true,
});

Migrating an Existing Bucket

If you need snapshots on an existing bucket, create a new one and copy:

tigris buckets create my-bucket-v2 --snapshot
tigris cp t3://my-bucket/ t3://my-bucket-v2/ -r
# Update your app to use the new bucket name
tigris buckets delete my-bucket  # when ready

---

How Automatic Tracking Works

Once snapshots are enabled, Tigris preserves every version of every object:

Timeline:
  T1: put("config.json", v1)        → v1 stored
  T2: put("config.json", v2)        → v2 stored, v1 still accessible
  T3: remove("config.json")         → deleted, but v1 and v2 still accessible
  T4: put("config.json", v3)        → v3 stored, v1, v2, and deletion all accessible

---

Restore from a Snapshot

The typical recovery workflow: list snapshots, pick one, restore files from it.

import { listBucketSnapshots, get, put } from "@tigrisdata/storage";

// 1. List snapshots
const result = await listBucketSnapshots("my-bucket");

// 2. Find the right one
const target = result.data?.find((s) => s.name === "before-deploy-v2.3");
const snapshotVersion = target!.version;

// 3. Read a file at that snapshot and write it back
const old = await get("config.json", "string", { snapshotVersion });
if (!old.error) {
  await put("config.json", old.data, { contentType: "application/json" });
}

For complete workflows including full bucket restore, prefix restore, timestamp-based recovery, and comparing snapshots — read ./resources/restore-workflows.md.

For Go SDK examples — read ./resources/go-examples.md.

For Python (tigris-boto3-ext) examples — read ./resources/python-examples.md. For full Python coverage (boto3 setup, Django, Bundle API), use the tigris-python-sdk skill.

---

Taking Explicit Snapshots (Optional Bookmarks)

While every change is tracked automatically, named snapshots make it easy to find specific points:

tigris snapshots take my-bucket --name "before-deploy-v2.3"
tigris snapshots list my-bucket

import { createBucketSnapshot } from "@tigrisdata/storage";
await createBucketSnapshot("my-bucket", { name: "before-deploy-v2.3" });

When to take explicit snapshots: Before deployments, migrations, bulk data operations, or any risky operation.

When you don't need them: For recovering a single file — just use a timestamp. Automatic tracking covers routine changes.

---

Critical Rules

Always:

• Enable snapshots when creating the bucket — you cannot add it later
• Use STANDARD storage tier for snapshot-enabled buckets
• Test recovery on a non-production bucket first
• Remember that any nanosecond timestamp works as a snapshot version

Never:

• Assume you can enable snapshots on an existing bucket (you must create a new one)
• Rely on explicit snapshots alone — automatic tracking means you can recover from any timestamp
• Use lifecycle rules or TTL on snapshot-enabled buckets (not supported)
• Forget to paginate when restoring many files

---

Known Issues

Problem	Fix
"Snapshots not enabled" error	Bucket was created without --snapshot / enableSnapshot: true. Create a new bucket and copy data.
Can't find the right timestamp	Take explicit named snapshots before risky operations for easy reference
Restore is slow for many files	Batch restores with concurrency limits; consider forking instead for full-bucket recovery
Snapshot bucket won't transition tiers	Snapshot buckets must use STANDARD tier — lifecycle transitions are not supported

---

Related Skills

• tigris-snapshots-forking — Forking buckets for dev sandboxes and testing
• file-storage — SDK reference for get, put, list
• tigris-backup-export — Complementary backup strategy with database dumps

Official Documentation

• Snapshots: https://www.tigrisdata.com/docs/buckets/snapshots-and-forks/