Bucket snapshots and forks

This page covers how to enable and use snapshots, forks, and object versioning on your Tigris buckets. For an overview of the concepts, see Snapshots and Forks.

Snapshots and forks are opt-in features. To enable them on a bucket, you must set a special header at creation time.

Enabling snapshots and forks

To enable snapshots and forks, set the X-Tigris-Enable-Snapshot: true header when creating the bucket.

Go

Example using the Go SDK github.com/aws/aws-sdk-go-v2/service/s3:

func createBucketWithSnapshotEnabled(ctx context.Context, client *s3.Client, bucketName string) error {
	_, err := client.CreateBucket(ctx, &s3.CreateBucketInput{Bucket: aws.String(bucketName)}, func(options *s3.Options) {
		options.APIOptions = append(options.APIOptions, http.AddHeaderValue("X-Tigris-Enable-Snapshot", "true"))
	})
	return err
}

JavaScript

Example using the Tigris SDK for JavaScript:

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

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

if (result.error) {
  console.error("error creating bucket with snapshots enabled", result.error);
} else {
  console.log("bucket created with snapshots enabled");
}

Python

Example using the Python SDK boto3:

pip install tigris-boto3-ext

import boto3
from tigris_boto3_ext import (
    TigrisSnapshotEnabled,
    create_snapshot_bucket,
)

# Initialize boto3 S3 client
s3_client = boto3.client(
    's3',
    endpoint_url='https://t3.storage.dev',  # Tigris endpoint
    aws_access_key_id='your-access-key',
    aws_secret_access_key='your-secret-key',
)

# Create snapshot enabled bucket using context manager pattern
with TigrisSnapshotEnabled(s3_client):
    s3_client.create_bucket(Bucket='my-snapshot-bucket')

# Or, create snapshot enabled bucket using helper function
create_snapshot_bucket(s3_client, 'my-snapshot-bucket')

Creating a snapshot

Snapshots are created with the same CreateBucket API call, with an additional header: X-Tigris-Snapshot: true.

Snapshot name can optionally be specified as part of that header (with semicolon separator), e.g., X-Tigris-Snapshot: true; name=test snapshot name.

The version of the snapshot created is returned in the X-Tigris-Snapshot-Version header of the response.

Go

Example using the Go SDK github.com/aws/aws-sdk-go-v2/service/s3:

func createBucketSnapshot(ctx context.Context, client *s3.Client, bucketName string, snapshotName string) (string, error) {
	resp, err := client.CreateBucket(ctx, &s3.CreateBucketInput{Bucket: aws.String(bucketName)}, func(options *s3.Options) {
		options.APIOptions = append(options.APIOptions, http.AddHeaderValue("X-Tigris-Snapshot", fmt.Sprintf("true; name=%s", snapshotName)))
	})
	if err != nil {
		return "", err
	}
	rawResp := middleware.GetRawResponse(resp.ResultMetadata).(*http.Response)
	return rawResp.Header.Get("X-Tigris-Snapshot-Version"), nil
}

JavaScript

Example using the Tigris SDK for JavaScript:

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

const result = await createBucketSnapshot("bucket-with-snapshots", {
  name: "test snapshot", // optional name for the snapshot
});

if (result.error) {
  console.error("error creating bucket snapshot", result.error);
} else {
  console.log("bucket snapshot created");
}

Python

Example using the Python SDK boto3:

pip install tigris-boto3-ext

import boto3
from tigris_boto3_ext import (
    create_snapshot_bucket,
    create_snapshot,
    get_snapshot_version,
)

# Initialize boto3 S3 client
s3_client = boto3.client(
    's3',
    endpoint_url='https://t3.storage.dev',  # Tigris endpoint
    aws_access_key_id='your-access-key',
    aws_secret_access_key='your-secret-key',
)

# Create snapshot-enabled bucket
create_snapshot_bucket(s3_client, 'bucket-with-snapshots')

# Create snapshots
result = create_snapshot(s3_client, 'bucket-with-snapshots', snapshot_name='test-snapshot')
version = get_snapshot_version(result)

Listing snapshots

Snapshots are listed with the same ListBuckets API call, with an additional header: X-Tigris-Snapshot: <BUCKET_NAME>.

To list snapshots for a bucket, make a list buckets request and set the X-Tigris-Snapshot header to the bucket name, e.g., X-Tigris-Snapshot: test-bucket.

Go

Example using the Go SDK github.com/aws/aws-sdk-go-v2/service/s3:

func listSnapshotsForBucket(ctx context.Context, client *s3.Client, bucketName string) (*s3.ListBucketsOutput, error) {
	return client.ListBuckets(ctx, &s3.ListBucketsInput{}, func(options *s3.Options) {
		options.APIOptions = append(options.APIOptions, http.AddHeaderValue("X-Tigris-Snapshot", bucketName))
	})
}

JavaScript

Example using the Tigris SDK for JavaScript:

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

const listSnapshots = await listBucketSnapshots("bucket-with-snapshots"); // bucket name

if (listSnapshots.error) {
  console.error("error listing snapshots", listSnapshots.error);
} else {
  console.log("snapshots:", listSnapshots.data);
}

Python

Example using the Python SDK boto3:

pip install tigris-boto3-ext

import boto3
from tigris_boto3_ext import (
    TigrisSnapshot,
    create_snapshot_bucket,
    list_snapshots,
)

# Initialize boto3 S3 client
s3_client = boto3.client(
    's3',
    endpoint_url='https://t3.storage.dev',  # Tigris endpoint
    aws_access_key_id='your-access-key',
    aws_secret_access_key='your-secret-key',
)

# Create snapshot-enabled bucket
create_snapshot_bucket(s3_client, 'bucket-with-snapshots')

# List snapshots for a bucket using context manager pattern
with TigrisSnapshot(s3_client, 'bucket-with-snapshots'):
    snapshots = s3_client.list_buckets()

# Or, list snapshots via the helper function
snapshots = list_snapshots(s3_client, 'bucket-with-snapshots')

Example list snapshots response

The response will contain the list of snapshots for the bucket including the name and creation date of the snapshot. The response format is S3-compatible. Name tag here showing snapshot version with the name if added during snapshot creation time.

<ListAllMyBucketsResult>
    <Buckets>
        <Bucket>
            <Name>1751631910196672425; name=my first snapshot</Name>
            <CreationDate>2025-07-04T12:25:10.19667705Z</CreationDate>
        </Bucket>
        <Bucket>
            <Name>1751631910169675092</Name>
            <CreationDate>2025-07-04T12:25:10.16968055Z</CreationDate>
        </Bucket>
        <Bucket>
            <Name>1751631910140685342; name=another snapshot</Name>
            <CreationDate>2025-07-04T12:25:10.141025675Z</CreationDate>
        </Bucket>
    </Buckets>
    <ContinuationToken>1751631910140685342</ContinuationToken>
</ListAllMyBucketsResult>

Creating a forked bucket

Forks are also created via the CreateBucket API, specifying a source bucket (and optionally a snapshot).

To create a bucket which is a fork of another bucket, specify the X-Tigris-Fork-Source-Bucket: <BUCKET_NAME> header where <BUCKET_NAME> is the name of the bucket you want to use as the fork source.

Add the X-Tigris-Fork-Source-Bucket-Snapshot: <SNAPSHOT_VERSION> header (e.g. X-Tigris-Fork-Source-Bucket-Snapshot: 1751631910140685342) if you want to use a specific snapshot of the source bucket for the fork. If this header is not set, then a new snapshot of the source bucket will be created at the current time and used for creating the fork bucket.

Go

Example using the Go SDK github.com/aws/aws-sdk-go-v2/service/s3:

func createBucketFork(ctx context.Context, client *s3.Client, bucketName string) error {
	_, err := client.CreateBucket(ctx, &s3.CreateBucketInput{Bucket: aws.String(bucketName)}, func(options *s3.Options) {
		options.APIOptions = append(options.APIOptions, http.AddHeaderValue("X-Tigris-Fork-Source-Bucket", "source-bucket"))
	})
	return err
}

JavaScript

Example using the Tigris SDK for JavaScript:

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

const result = await createBucket("forked-bucket", {
  sourceBucketName: "source-bucket", // source bucket name
  sourceBucketSnapshot: "snapshot_version", // optional snapshot version e.g. 1759343574493973169
});

if (result.error) {
  console.error("error creating bucket fork", result.error);
} else {
  console.log("bucket fork created");
}

Python

Example using the Python SDK boto3:

pip install tigris-boto3-ext

import boto3
from tigris_boto3_ext import (
    TigrisFork,
    create_fork
)

# Initialize boto3 S3 client
s3_client = boto3.client(
    's3',
    endpoint_url='https://t3.storage.dev',  # Tigris endpoint
    aws_access_key_id='your-access-key',
    aws_secret_access_key='your-secret-key',
)

# Fork from current state
with TigrisFork(s3_client, 'source-bucket'):
    s3_client.create_bucket(Bucket='forked-bucket')

# Fork from specific snapshot
with TigrisFork(s3_client, 'source-bucket', snapshot_version='1759343574493973169'):
    s3_client.create_bucket(Bucket='forked-from-snapshot')

# Or, use a helper function to create forks
create_fork(s3_client, 'new-bucket', 'source-bucket', snapshot_version='1759343574493973169')

Retrieving snapshot and fork info for a bucket

Information related to snapshots and forks for an existing bucket can be retrieved by making a HeadBucket request. The response of the request will include custom Tigris headers with the details:

• The X-Tigris-Enable-Snapshot header will always be present and will be set to "true" for snapshot-enabled buckets.
• X-Tigris-Fork-Source-Bucket and X-Tigris-Fork-Source-Bucket-Snapshot will only be set for fork buckets and will contain the source bucket name and snapshot versions respectively.
• X-Tigris-Is-Fork-Parent will only be present for source buckets that have forks and will be set to "true".

Note: These are not standard AWS S3 headers, and in order to retrieve them, the raw HTTP response will need to be used. Here is an example for checking whether snapshot is enabled for a bucket:

Go

Example using the Go SDK github.com/aws/aws-sdk-go-v2/service/s3:

func hasSnapshotEnabled(ctx context.Context, client *s3.Client, bucketName string) (bool, error) {
	resp, err := client.HeadBucket(ctx, &s3.HeadBucketInput{Bucket: aws.String(bucketName)})
	if err != nil {
		return false, err
	}
	rawResp := middleware.GetRawResponse(resp.ResultMetadata).(*http.Response)
	return rawResp.Header.Get("X-Tigris-Enable-Snapshot") == "true", nil
}

JavaScript

Example using the AWS SDK for JavaScript v3:

import { S3Client, HeadBucketCommand } from "@aws-sdk/client-s3";

async function hasSnapshotEnabled(s3Client, bucketName) {
  const response = await s3Client.send(
    new HeadBucketCommand({ Bucket: bucketName }),
  );
  const headers = response.$metadata?.httpHeaders || {};
  return headers["X-Tigris-Enable-Snapshot"] === "true";
}

Python

Example using the Python SDK boto3:

pip install tigris-boto3-ext

import boto3
from tigris_boto3_ext import (
    create_snapshot_bucket,
    create_snapshot,
    create_fork,
    get_snapshot_version,
    has_snapshot_enabled,
    get_bucket_info,
)

# Initialize boto3 S3 client
s3_client = boto3.client(
    's3',
    endpoint_url='https://t3.storage.dev',  # Tigris endpoint
    aws_access_key_id='your-access-key',
    aws_secret_access_key='your-secret-key',
)

# Check if a bucket has snapshots enabled
bucket_name = 'my-bucket'

create_snapshot_bucket(s3_client, bucket_name)

if has_snapshot_enabled(s3_client, bucket_name):
    print(f"✓ Snapshots are enabled for {bucket_name}")
else:
    print(f"✗ Snapshots are not enabled for {bucket_name}")

# Example: Check fork lineage
source_bucket = 'production-data'
create_snapshot_bucket(s3_client, source_bucket)

# Create a snapshot
snapshot_result = create_snapshot(s3_client, source_bucket, snapshot_name='v1')
snapshot_version = get_snapshot_version(snapshot_result)

# Create a fork
forked_bucket = 'test-data'
create_fork(s3_client, forked_bucket, source_bucket, snapshot_version=snapshot_version)

# Inspect the fork
fork_info = get_bucket_info(s3_client, forked_bucket)
print(f"Forked from: {fork_info['fork_source_bucket']}")
print(f"Snapshot version: {fork_info['fork_source_snapshot']}")

Retrieving objects in a snapshot

Existing APIs can be used to retrieve objects in a snapshot when an additional header is set:

• To list objects use ListObjectsV2
• To get objects use GetObject
• To head objects use HeadObject
• To copy objects use CopyObject

Additional header: X-Tigris-Snapshot-Version: SNAPSHOT_VERSION needs to be set when making these requests to retrieve objects from a specific snapshot.

note

Any UNIX nanosecond-precision timestamp (e.g., 1765889000501544464) can be used as a snapshot parameter value for ListObjectsV2, GetObject, HeadObject and CopyObject API calls, even if there is no snapshot created at that particular time.

Below is an example of retrieving an object from a snapshot:

Go

Example using the Go SDK github.com/aws/aws-sdk-go-v2/service/s3:

func getObjectFromSnapshot(ctx context.Context, client *s3.Client, bucket string, object string, snapshotVersion string) (*s3.GetObjectOutput, error) {
	return client.GetObject(ctx, &s3.GetObjectInput{Bucket: aws.String(bucket), Key: aws.String(object)}, func(options *s3.Options) {
		options.APIOptions = append(options.APIOptions, http.AddHeaderValue("X-Tigris-Snapshot-Version", snapshotVersion))
	})
}

JavaScript

Example using the AWS SDK for JavaScript v3:

import { S3Client, GetObjectCommand } from "@aws-sdk/client-s3";

async function getObjectFromSnapshot(client, bucket, key, snapshotVersion) {
  return client.send(
    new GetObjectCommand({
      Bucket: bucket,
      Key: key,
      $httpOptions: {
        headers: { "X-Tigris-Snapshot-Version": snapshotVersion },
      },
    }),
  );
}

Python

Example using the Python SDK boto3:

pip install tigris-boto3-ext

import boto3
from tigris_boto3_ext import (
    TigrisSnapshot,
    create_snapshot_bucket,
    create_snapshot,
    get_object_from_snapshot,
    get_snapshot_version,
    head_object_from_snapshot,
    list_objects_from_snapshot,
)

# Initialize boto3 S3 client
s3_client = boto3.client(
    's3',
    endpoint_url='https://t3.storage.dev',  # Tigris endpoint
    aws_access_key_id='your-access-key',
    aws_secret_access_key='your-secret-key',
)

# First, ensure bucket has snapshots enabled
create_snapshot_bucket(s3_client, 'my-bucket')
s3_client.put_object(Bucket='my-bucket', Key='file.txt', Body=b'data')

response = create_snapshot(
    s3_client,
    'my-bucket',
    snapshot_name='daily-backup-2024-01-01'
)
snapshot_version = get_snapshot_version(response)
print(f"Snapshot version: {snapshot_version}")

# Read objects from a specific snapshot using context manager pattern
with TigrisSnapshot(s3_client, 'my-bucket', snapshot_version=snapshot_version):
    obj = s3_client.get_object(Bucket='my-bucket', Key='file.txt')
    objects = s3_client.list_objects_v2(Bucket='my-bucket')

# Or, use a helper function to access snapshot data
obj = get_object_from_snapshot(s3_client, 'my-bucket', 'file.txt', snapshot_version)
objects = list_objects_from_snapshot(s3_client, 'my-bucket', snapshot_version)
metadata = head_object_from_snapshot(s3_client, 'my-bucket', 'file.txt', snapshot_version)

note

Check out the examples in the tigris-boto3-ext repo for more details on how to use the snapshot and forking feature with the Python boto3 SDK.

Using object versioning APIs

Working with a snapshot-enabled bucket sometimes requires reading or deleting a specific version of an object - for example, fetching a known prior version directly, or permanently removing a single version across the bucket and its snapshots. A subset of S3-compatible object versioning APIs supports these cases without any additional changes. No special headers or extra steps are required, and standard SDKs and tools work as-is.

Supported APIs

• ListObjectVersions
• HeadObject with the versionId parameter
• GetObject with the versionId parameter
• DeleteObject with the versionId parameter

note

As in S3, deleting an object with a specified version ID permanently removes that version. It is also deleted from all snapshots.

No additional authorization permissions are required to use the HeadObject or GetObject APIs with the versionId parameter. The ListObjectVersions operation is available to users with read-only (or higher) access to the bucket. However, note that this is a separate operation, and some IAM policies may need to be updated to allow it.

Using a forked bucket

Forked buckets behave the same as regular buckets, and you can use the usual tooling (AWS CLI or SDK) to work with them.

The only restriction is that the source bucket cannot be deleted while forked buckets depend on it.

Authorization

Snapshot and fork operations on existing buckets are limited to users who are bucket owners, organization admins, or have ReadOnly (or Editor) access to the buckets. This includes all operations mentioned above, such as creating a snapshot, creating a fork from a specific source bucket, or listing objects in a snapshot.