Tigris Snapshots Forking

tigrisdata/skills/skills/tigris-snapshots-forking

作者 tigrisdata668ea424758e无许可证2 个星标收录于 2026年10月8日更新于 2026年10月8日仓库2个月前更新

Use when needing point-in-time recovery, version control for object storage, or creating isolated bucket copies for testing/experimentation

仅含说明DevOps & Cloud

AI 生成的概览

讲解 Tigris 对象存储快照与分叉，用于时间点恢复和隔离的存储桶副本。

功能: 该技能说明如何通过 @tigrisdata/storage 库使用 Tigris 快照和存储桶分叉。内容涵盖创建和列出快照、从快照分叉存储桶、按快照版本读取对象，以及写时复制隔离如何保护源数据。它还列出前提条件、限制、常见错误，以及沙箱、智能体环境和迁移前备份等用例。
适用场景: 当你需要时间点恢复、对象存储的版本控制，或用于测试和实验的隔离存储桶副本时使用。它适用于开发者沙箱、AI 智能体环境、负载测试和迁移前备份等场景。
运行要求: 需要 Tigris CLI（@tigrisdata/cli）和 @tigrisdata/storage 库，并能访问 Tigris 对象存储。存储桶必须在创建时启用 enableSnapshot: true，并使用 STANDARD 存储层级。该技能不附带脚本，仅为说明文档。

Tigris Snapshots and Forking

Prerequisites

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

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

Overview

Snapshots capture your entire bucket at a point in time. Forking creates instant, isolated copies from snapshots using copy-on-write.

Core principle: Snapshots and forks protect your data from deletion. Even if you delete everything in a fork, the source bucket data remains intact.

Why Snapshots Matter

Object storage serves as the primary data store for many systems. It needs safety features:

Point-in-time recovery - Restore after accidental deletion or corruption
Version control - Tag meaningful states like releases
Reproducibility - Recreate exact environments for debugging or testing
Deletion protection - Forks can be destroyed without affecting source

Traditional object versioning only works per-object. To restore a bucket to a point in time, you must check and restore each object individually. Tigris snapshots capture the entire bucket state instantly.

Why Forking Matters

Forking creates isolated bucket copies instantly - even for terabytes of data:

Developer sandboxes - Test with real production data safely
AI agent environments - Spin up agents with pre-loaded dependencies
Load testing - Use production data without risk
Feature branch testing - Parallel environments for experiments
Training experiments - Fork datasets to test without affecting source

How it works: Tigris uses immutable objects with backwards-ordered timestamps. Forks read from the parent snapshot until new data overwrites. This makes forking essentially free - no data copying required.

Quick Reference

Operation	Function	Key Parameters
Create snapshot	`createBucketSnapshot(options)`	name, sourceBucketName
List snapshots	`listBucketSnapshots(sourceBucketName)`	sourceBucketName
Create fork	`createBucket(name, options)`	sourceBucketName, sourceBucketSnapshot

Create Snapshot

typescript

import { createBucketSnapshot } from "@tigrisdata/storage";
// Snapshot default bucketconst result = await createBucketSnapshot();if (result.error) {  console.error("Error:", result.error);} else {  console.log("Snapshot version:", result.data?.snapshotVersion);  // Output: { snapshotVersion: "1751631910169675092" }}
// Named snapshot for specific bucketconst result = await createBucketSnapshot("my-bucket", {  name: "backup-before-migration",});if (result.error) {  console.error("Error:", result.error);} else {  console.log("Named snapshot:", result.data?.snapshotVersion);}

import { createBucketSnapshot } from "@tigrisdata/storage";
// Snapshot default bucketconst result = await createBucketSnapshot();if (result.error) {  console.error("Error:", result.error);} else {  console.log("Snapshot version:", result.data?.snapshotVersion);  // Output: { snapshotVersion: "1751631910169675092" }}
// Named snapshot for specific bucketconst result = await createBucketSnapshot("my-bucket", {  name: "backup-before-migration",});if (result.error) {  console.error("Error:", result.error);} else {  console.log("Named snapshot:", result.data?.snapshotVersion);}

Prerequisite: Bucket must have enableSnapshot: true when created.

List Snapshots

typescript

import { listBucketSnapshots } from "@tigrisdata/storage";
// List snapshots for default bucketconst result = await listBucketSnapshots();if (result.error) {  console.error("Error:", result.error);} else {  console.log("Snapshots:", result.data);  // [  //   {  //     name: "backup-before-migration",  //     version: "1751631910169675092",  //     creationDate: Date("2025-01-15T08:30:00Z")  //   }  // ]}
// List snapshots for specific bucketconst result = await listBucketSnapshots("my-bucket");

import { listBucketSnapshots } from "@tigrisdata/storage";
// List snapshots for default bucketconst result = await listBucketSnapshots();if (result.error) {  console.error("Error:", result.error);} else {  console.log("Snapshots:", result.data);  // [  //   {  //     name: "backup-before-migration",  //     version: "1751631910169675092",  //     creationDate: Date("2025-01-15T08:30:00Z")  //   }  // ]}
// List snapshots for specific bucketconst result = await listBucketSnapshots("my-bucket");

Create Fork from Snapshot

typescript

import { createBucket, createBucketSnapshot } from "@tigrisdata/storage";
// First, create a snapshotconst snapshot = await createBucketSnapshot("agent-seed", {  name: "agent-seed-v1",});const snapshotVersion = snapshot.data?.snapshotVersion;
// Fork from snapshotconst agentBucketName = `agent-${Date.now()}`;const forkResult = await createBucket(agentBucketName, {  sourceBucketName: "agent-seed",  sourceBucketSnapshot: snapshotVersion,});
if (forkResult.error) {  console.error("Error:", forkResult.error);} else {  console.log("Forked bucket created");  // agent-${timestamp} has all data from agent-seed at snapshot time  // Can modify/delete freely - agent-seed is unaffected}

import { createBucket, createBucketSnapshot } from "@tigrisdata/storage";
// First, create a snapshotconst snapshot = await createBucketSnapshot("agent-seed", {  name: "agent-seed-v1",});const snapshotVersion = snapshot.data?.snapshotVersion;
// Fork from snapshotconst agentBucketName = `agent-${Date.now()}`;const forkResult = await createBucket(agentBucketName, {  sourceBucketName: "agent-seed",  sourceBucketSnapshot: snapshotVersion,});
if (forkResult.error) {  console.error("Error:", forkResult.error);} else {  console.log("Forked bucket created");  // agent-${timestamp} has all data from agent-seed at snapshot time  // Can modify/delete freely - agent-seed is unaffected}

Read from Snapshot Version

Access historical data without forking:

typescript

import { get, list } from "@tigrisdata/storage";
// Get object as it was at snapshotconst result = await get("config.json", "string", {  snapshotVersion: "1751631910169675092",});
// List objects as they were at snapshotconst result = await list({  snapshotVersion: "1751631910169675092",});

import { get, list } from "@tigrisdata/storage";
// Get object as it was at snapshotconst result = await get("config.json", "string", {  snapshotVersion: "1751631910169675092",});
// List objects as they were at snapshotconst result = await list({  snapshotVersion: "1751631910169675092",});

Deletion Protection in Action

typescript

import { remove, get } from "@tigrisdata/storage";
// In forked bucket, delete everythingawait remove("hello.txt", { config: { bucket: "agent-fork" } });
// Fork appears emptyconst forkResult = await get("hello.txt", "string", {  config: { bucket: "agent-fork" },});// forkResult.error === "Not found"
// But source bucket still has dataconst sourceResult = await get("hello.txt", "string", {  config: { bucket: "agent-seed" },});// sourceResult.data === "Hello, world!"

import { remove, get } from "@tigrisdata/storage";
// In forked bucket, delete everythingawait remove("hello.txt", { config: { bucket: "agent-fork" } });
// Fork appears emptyconst forkResult = await get("hello.txt", "string", {  config: { bucket: "agent-fork" },});// forkResult.error === "Not found"
// But source bucket still has dataconst sourceResult = await get("hello.txt", "string", {  config: { bucket: "agent-seed" },});// sourceResult.data === "Hello, world!"

The fork's deletion only affects the fork. Source data remains accessible in the parent bucket and all snapshots.

Use Cases

Developer Sandboxes

typescript

// Create snapshot of production dataawait createBucketSnapshot("production", {  name: "dev-sandbox-seed",});
// Fork for each developerconst devBucket = await createBucket(`dev-${developerName}`, {  sourceBucketName: "production",  sourceBucketSnapshot: "...",});// Developer can test and modify freely

// Create snapshot of production dataawait createBucketSnapshot("production", {  name: "dev-sandbox-seed",});
// Fork for each developerconst devBucket = await createBucket(`dev-${developerName}`, {  sourceBucketName: "production",  sourceBucketSnapshot: "...",});// Developer can test and modify freely

AI Agent Environments

typescript

// Store agent dependencies in seed bucketawait put("model.bin", modelData);await put("config.json", agentConfig);
// Snapshot the seedconst snapshot = await createBucketSnapshot("agent-seed", {  name: "v1",});
// Spin up new agent instance with forkconst agentBucket = `agent-${Date.now()}`;await createBucket(agentBucket, {  sourceBucketName: "agent-seed",  sourceBucketSnapshot: snapshot.data?.snapshotVersion,});
// Agent has everything and can modify freelyawait startAgent(agentBucket);

// Store agent dependencies in seed bucketawait put("model.bin", modelData);await put("config.json", agentConfig);
// Snapshot the seedconst snapshot = await createBucketSnapshot("agent-seed", {  name: "v1",});
// Spin up new agent instance with forkconst agentBucket = `agent-${Date.now()}`;await createBucket(agentBucket, {  sourceBucketName: "agent-seed",  sourceBucketSnapshot: snapshot.data?.snapshotVersion,});
// Agent has everything and can modify freelyawait startAgent(agentBucket);

Pre-Migration Backups

typescript

// Before risky operationawait createBucketSnapshot("production", {  name: "before-migration-v2",});
// Run migration// If disaster strikes, fork from snapshot to recoverconst rollback = await createBucket("production-restored", {  sourceBucketName: "production",  sourceBucketSnapshot: "...",});

// Before risky operationawait createBucketSnapshot("production", {  name: "before-migration-v2",});
// Run migration// If disaster strikes, fork from snapshot to recoverconst rollback = await createBucket("production-restored", {  sourceBucketName: "production",  sourceBucketSnapshot: "...",});

Common Mistakes

Mistake	Fix
Snapshotting non-snapshot-enabled bucket	Recreate bucket with `enableSnapshot: true`
Expecting fork to affect source	Forks are isolated - source remains unchanged
Not naming snapshots	Names make snapshots discoverable
Using wrong storage tier	Snapshot buckets must use STANDARD tier

Limitations

Existing buckets cannot be snapshot-enabled (must create new bucket)
Snapshot buckets require STANDARD storage tier
Snapshot buckets don't support lifecycle transitions or TTL

How It Works (Deep Dive)

A snapshot is a single 64-bit integer representing nanoseconds since Unix epoch. Tigris stores objects with reverse-ordered timestamps, so the most recent version sorts first. When you snapshot, Tigris records the current time. Reading from a snapshot queries for the newest object version before that timestamp.

Forking adds recursive indirection: child bucket objects override the parent, but missing objects recurse through the parent snapshot. This makes forking instant - no data copying, just metadata pointers.

来源与署名

来源：tigrisdata/skills位于skills/tigris-snapshots-forking提交668ea42

许可证：无许可证

内容归原作者所有。SourceWeft 从公开仓库中收录这些内容。

举报或申请下架

Tigris Snapshots Forking

Tigris Snapshots and Forking

Prerequisites

Overview

Why Snapshots Matter

Why Forking Matters

Quick Reference

Create Snapshot

List Snapshots

Create Fork from Snapshot

Read from Snapshot Version

Deletion Protection in Action

Use Cases

Developer Sandboxes

AI Agent Environments

Pre-Migration Backups

Common Mistakes

Limitations

How It Works (Deep Dive)

来源与署名

更多来自 tigrisdata/skills 的技能

Tigris Sdk Guide

Tigris Image Optimization

Tigris Object Operations

更多DevOps & Cloud技能

Playwright Devops

M5 Onboard

Yeet

Runbook

Incident Response

Deploy Checklist