storage

package module
v0.8.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 11, 2026 License: MIT Imports: 26 Imported by: 0

README

Tigris Storage SDK for Go

Welcome to the Tigris Storage SDK for Go! This package contains high-level wrappers and helpers to help you take advantage of all of Tigris' features.

Overview

Tigris is a cloud storage service that provides a simple, scalable, and secure object storage solution. It is based on the S3 API, but has additional features that need these helpers.

This SDK provides the main storage package containing the Tigris client with S3-compatible methods plus Tigris-specific features like bucket forking, snapshots, soft delete, and object renaming.

Installation

go get github.com/tigrisdata/storage-go

Quick Start

package main

import (
    "context"
    "fmt"
    "log"

    storage "github.com/tigrisdata/storage-go"
)

func main() {
    ctx := context.Background()

    // Create a new Tigris client
    client, err := storage.New(ctx)
    if err != nil {
        log.Fatal(err)
    }

    // Use the client like you would use AWS S3 client
    // plus Tigris-specific features (see below)
    fmt.Println("Connected to Tigris!")
}

Client Configuration

The New() function creates a new S3 client optimized for interactions with Tigris. It accepts functional options to configure the client:

client, err := storage.New(ctx,
    storage.WithFlyEndpoint(),           // Use fly.io optimized endpoint
    storage.WithGlobalEndpoint(),        // Use globally available endpoint (default)
    storage.WithRegion("auto"),          // Specify a region
    storage.WithAccessKeypair(key, secret), // Set access credentials
)
Configuration Options
Option Description
WithFlyEndpoint() Connect to Tigris' fly.io optimized endpoint. If you are deployed to fly.io, this zero-rates your traffic to Tigris.
WithGlobalEndpoint() Connect to Tigris' globally available endpoint (https://t3.storage.dev). This is the default.
WithRegion(region) Statically specify a region for interacting with Tigris. You will almost certainly never need this.
WithAccessKeypair(accessKeyID, secretAccessKey) Specify a custom access key and secret access key. Useful when loading credentials from non-standard locations.

Bucket Features

Snapshots and Forks

Tigris supports bucket snapshots and forking, allowing you to create point-in-time copies of buckets and branch from them.

Create a Snapshot Enabled Bucket
output, err := client.CreateSnapshotEnabledBucket(ctx, &s3.CreateBucketInput{
    Bucket: aws.String("my-bucket"),
})
Create a Snapshot
output, err := client.CreateBucketSnapshot(ctx, "Initial backup", &s3.CreateBucketInput{
    Bucket: aws.String("my-bucket"),
})
// output.SnapshotVersion holds the version returned by Tigris.
Fork a Bucket
// Creates a new bucket "my-bucket-fork" as a fork of "my-bucket"
output, err := client.CreateBucketFork(ctx, "my-bucket", "my-bucket-fork")
List Snapshots
snapshots, err := client.ListBucketSnapshots(ctx, "my-bucket")
Get Fork/Snapshot Metadata
info, err := client.HeadBucketForkOrSnapshot(ctx, &s3.HeadBucketInput{
    Bucket: aws.String("my-bucket"),
})
// info.SnapshotsEnabled     - true if snapshots are enabled
// info.SourceBucket         - The bucket this was forked from
// info.SourceBucketSnapshot - The snapshot this was forked from
// info.IsForkParent         - true if there are forks of this bucket
Soft Delete

Soft delete moves a deleted object or bucket into a recoverable state for a retention window. The window is 7 days by default. A custom window must be between 7 and 90 days. Soft delete is a bucket-level setting, so it covers the bucket and every object in it.

Create a Bucket With Soft Delete
// Default 7-day retention window
_, err := client.CreateBucketWithSoftDelete(ctx, &storage.CreateBucketWithSoftDeleteInput{
    CreateBucketInput: &s3.CreateBucketInput{
        Bucket: aws.String("my-bucket"),
    },
})

// Custom 30-day retention window
_, err = client.CreateBucketWithSoftDelete(ctx, &storage.CreateBucketWithSoftDeleteInput{
    CreateBucketInput: &s3.CreateBucketInput{
        Bucket: aws.String("my-other-bucket"),
    },
    RetentionDays: 30,
})
Enable or Disable Soft Delete on an Existing Bucket
_, err := client.SetBucketSoftDelete(ctx, &storage.SetBucketSoftDeleteInput{
    Bucket:        "my-bucket",
    Enabled:       true,
    RetentionDays: 30, // omit for the default 7-day window
})
List and Restore Soft-Deleted Objects
listed, err := client.ListSoftDeletedObjects(ctx, &storage.ListSoftDeletedObjectsInput{
    Bucket: "my-bucket",
    Prefix: "logs/", // optional
})
// listed.Objects[i].Key          - object key
// listed.Objects[i].VersionID    - version to restore or permanently delete
// listed.Objects[i].Size         - original size in bytes
// listed.Objects[i].LastModified - time the object was soft-deleted
// listed.IsTruncated             - true if more pages are available

// Restore the most recent soft-deleted version
_, err = client.RestoreSoftDeletedObject(ctx, &storage.RestoreSoftDeletedObjectInput{
    Bucket: "my-bucket",
    Key:    "my-key",
})

// Restore one specific version
_, err = client.RestoreSoftDeletedObject(ctx, &storage.RestoreSoftDeletedObjectInput{
    Bucket:    "my-bucket",
    Key:       "my-key",
    VersionID: listed.Objects[0].VersionID,
})

To read the next page, pass listed.NextKeyMarker and listed.NextVersionIDMarker back as KeyMarker and VersionIDMarker.

List and Restore Soft-Deleted Buckets

A soft-deleted bucket keeps its name reserved until the retention window expires. RetentionDays is the window the bucket was configured with. It is not a countdown: a bucket deleted 6 days ago with a 30-day window still reports 30.

listed, err := client.ListSoftDeletedBuckets(ctx, nil)
// listed.Buckets[i].Name          - bucket to restore
// listed.Buckets[i].RetentionDays - the configured window in days

_, err = client.RestoreBucket(ctx, &storage.RestoreBucketInput{
    Bucket: "my-bucket",
})
Delete a Bucket That Is Not Empty

ForceDeleteBucket deletes a bucket and its contents in one call. If soft delete is enabled on the bucket, RestoreBucket can recover it.

[!CAUTION] Do not call ForceDeleteBucket on a bucket without soft delete. The bucket and every object in it are removed permanently. Support cannot recover them.

_, err := client.ForceDeleteBucket(ctx, &s3.DeleteBucketInput{
    Bucket: aws.String("my-bucket"),
})
Purge a Soft-Deleted Version

PermanentlyDeleteObject removes one soft-deleted version before its retention window expires. The version ID is required. Get it from ListSoftDeletedObjects.

[!CAUTION] Do not call PermanentlyDeleteObject unless you accept the loss of the data. The version is removed permanently. Support cannot recover it.

_, err := client.PermanentlyDeleteObject(ctx, "my-bucket", "my-key", "1775929768707198086")
Error Handling

ListSoftDeletedObjects, ListSoftDeletedBuckets, RestoreSoftDeletedObject, RestoreBucket, and SetBucketSoftDelete send their requests to Tigris endpoints that the S3 SDK cannot express. When Tigris rejects one of these requests, the method returns a *storage.APIError. This type implements smithy.APIError, so errors.As reads it the same way it reads an error from the embedded S3 client:

_, err := client.RestoreBucket(ctx, &storage.RestoreBucketInput{Bucket: "my-bucket"})

var apiErr smithy.APIError
if errors.As(err, &apiErr) && apiErr.ErrorCode() == "NoSuchBucket" {
    // the bucket is gone
}

For the HTTP status code and the request ID, match the concrete type:

var apiErr *storage.APIError
if errors.As(err, &apiErr) {
    log.Printf("HTTP %d %s: %s (request %s)",
        apiErr.StatusCode, apiErr.Code, apiErr.Message, apiErr.RequestID)
}

Object Features

Rename Objects

Tigris supports in-place object renaming without copying data:

_, err := client.RenameObject(ctx, &s3.CopyObjectInput{
    Bucket:     aws.String("my-bucket"),
    CopySource: aws.String("my-bucket/old-name.txt"),
    Key:        aws.String("new-name.txt"),
})

Documentation

For more information on Tigris features, see:

License

See LICENSE for details.

Documentation

Overview

Package storage contains a Tigris client and helpers for interacting with Tigris.

Tigris is a cloud storage service that provides a simple, scalable, and secure object storage solution. It is based on the S3 API, but has additional features that need these helpers.

Index

Examples

Constants

View Source 
const (
	// BundleFormatTar is the tar archive format for bundle responses.
	BundleFormatTar = "tar"

	// BundleCompressionNone disables compression (default).
	BundleCompressionNone = "none"
	// BundleCompressionGzip enables gzip compression.
	BundleCompressionGzip = "gzip"
	// BundleCompressionZstd enables zstd compression.
	BundleCompressionZstd = "zstd"

	// BundleOnErrorSkip silently omits missing objects from the archive (default).
	BundleOnErrorSkip = "skip"
	// BundleOnErrorFail returns an error if any object is missing.
	BundleOnErrorFail = "fail"
)
View Source 
const (
	GlobalEndpoint = "https://t3.storage.dev"
	FlyEndpoint    = "https://fly.storage.tigris.dev"
)

Variables

View Source 
var (
	// ErrMissingBucket is returned when a required bucket name is empty.
	ErrMissingBucket = errors.New("bucket is required")
	// ErrMissingKey is returned when a required object key is empty.
	ErrMissingKey = errors.New("key is required")
	// ErrMissingVersionID is returned when a required version ID is empty.
	ErrMissingVersionID = errors.New("version ID is required")
)

Sentinel errors returned when a required argument is missing. They are wrapped with the calling method's name, so callers can match them with errors.Is.

Functions

This section is empty.

Types

type APIError added in v0.8.0 

type APIError struct {
	// Op is the name of the method that failed, such as "RestoreBucket".
	Op string
	// StatusCode is the HTTP status code of the response.
	StatusCode int
	// Code is the error code from the response body, such as "NoSuchBucket". It
	// is empty when the body is not an S3-style error document.
	Code string
	// Message is the error message from the response body. It holds the raw body
	// when the body is not an S3-style error document.
	Message string
	// RequestID identifies the failed request server-side. Give it to support
	// when you report a problem. Optional.
	RequestID string
}

APIError is returned when Tigris rejects one of the raw-HTTP requests this package sends for the endpoints the S3 SDK cannot express.

It implements smithy.APIError, so errors.As reads it the same way it reads errors from the embedded *s3.Client: 

var apiErr smithy.APIError
if errors.As(err, &apiErr) && apiErr.ErrorCode() == "NoSuchBucket" {
    // the bucket is gone
}

The HTTP status code is available from the StatusCode field and from HTTPStatusCode, which is the accessor the AWS SDK response errors expose.

func (*APIError) Error added in v0.8.0 

func (e *APIError) Error() string

Error implements the error interface.

func (*APIError) ErrorCode added in v0.8.0 

func (e *APIError) ErrorCode() string

ErrorCode implements smithy.APIError.

func (*APIError) ErrorFault added in v0.8.0 

func (e *APIError) ErrorFault() smithy.ErrorFault

ErrorFault implements smithy.APIError. A 4xx status is the fault of the client, a 5xx status is the fault of the server.

func (*APIError) ErrorMessage added in v0.8.0 

func (e *APIError) ErrorMessage() string

ErrorMessage implements smithy.APIError.

func (*APIError) HTTPStatusCode added in v0.8.0 

func (e *APIError) HTTPStatusCode() int

HTTPStatusCode returns the HTTP status code of the response. It matches the accessor on the response errors of the AWS SDK, so a caller can read the status through one interface for both error sources.

type BundleObjectsInput added in v0.6.0 

type BundleObjectsInput struct {
	// Bucket is the name of the bucket containing the objects. Required.
	Bucket string

	// Keys is the list of object keys to include in the bundle. Required.
	// Maximum 5,000 keys per request.
	Keys []string

	// Compression sets the compression algorithm for the response.
	// Valid values: "none" (default), "gzip", "zstd".
	Compression string

	// OnError controls behavior when objects are missing.
	// "skip" (default): omit missing objects and append __bundle_errors.json to the tar.
	// "fail": return an error before streaming if any object is missing.
	OnError string
}

BundleObjectsInput is the input for a BundleObjects request.

type BundleObjectsOutput added in v0.6.0 

type BundleObjectsOutput struct {
	// Body is the streaming tar archive. Must be closed by the caller.
	Body io.ReadCloser

	// ContentType is the response Content-Type (e.g. "application/x-tar", "application/gzip").
	ContentType string

	// StatusCode is the HTTP status code of the response.
	StatusCode int
}

BundleObjectsOutput is the response from a BundleObjects request.

The Body contains a streaming tar archive. Callers are responsible for closing Body. Use archive/tar to iterate entries: 

tr := tar.NewReader(output.Body)
for {
    hdr, err := tr.Next()
    if err == io.EOF { break }
    // process hdr.Name, tr
}

If compression was requested, wrap Body with the appropriate decompressor first: 

gz, _ := gzip.NewReader(output.Body)
tr := tar.NewReader(gz)

type Client 

type Client struct {
	*s3.Client
}

Client is a wrapper around the AWS SDK S3 Client with additional methods for integration with Tigris.

func New 

func New(ctx context.Context, options ...Option) (*Client, error)

New returns a new S3 client optimized for interactions with Tigris.

Example 
package main

import (
	"context"
	"log"

	storage "github.com/tigrisdata/storage-go"

	_ "github.com/joho/godotenv/autoload"
)

func main() {
	ctx := context.Background()

	// Create a new Tigris client with default options
	client, err := storage.New(ctx)
	if err != nil {
		log.Fatal(err)
	}
	_ = client

	// Create a client with custom options
	client, err = storage.New(ctx,
		storage.WithFlyEndpoint(),    // Use fly.io optimized endpoint
		storage.WithGlobalEndpoint(), // Use globally available endpoint (default)
		storage.WithRegion("auto"),   // Specify a region
		// storage.WithAccessKeypair(key, secret), // Set access credentials
	)
	if err != nil {
		log.Fatal(err)
	}
	_ = client
}

func (*Client) BundleObjects added in v0.6.0 

func (c *Client) BundleObjects(ctx context.Context, in *BundleObjectsInput) (*BundleObjectsOutput, error)

BundleObjects fetches multiple objects from a bucket as a streaming tar archive in a single HTTP request.

This is a Tigris extension to the S3 API, designed for ML training workloads that need to fetch thousands of objects per batch without per-object HTTP overhead.

The caller is responsible for closing the returned Body.

Example 
package main

import (
	"archive/tar"
	"context"
	"io"
	"log"

	storage "github.com/tigrisdata/storage-go"

	_ "github.com/joho/godotenv/autoload"
)

func main() {
	ctx := context.Background()

	client, err := storage.New(ctx)
	if err != nil {
		log.Fatal(err) // handle the error here
	}

	// Fetch multiple objects as a streaming tar archive in a single request.
	output, err := client.BundleObjects(ctx, &storage.BundleObjectsInput{
		Bucket: "my-dataset-bucket",
		Keys: []string{
			"train/img_001.jpg",
			"train/img_002.jpg",
			"train/img_003.jpg",
		},
	})
	if err != nil {
		log.Fatal(err) // handle the error here
	}
	defer output.Body.Close()

	// Iterate tar entries as they arrive.
	tr := tar.NewReader(output.Body)
	for {
		hdr, err := tr.Next()
		if err == io.EOF {
			break
		}
		if err != nil {
			log.Fatal(err) // handle the error here
		}

		// Read the object content.
		data, err := io.ReadAll(tr)
		if err != nil {
			log.Fatal(err) // handle the error here
		}

		_ = hdr.Name // object key, e.g. "train/img_001.jpg"
		_ = data     // object content
	}
}

func (*Client) CreateBucketFork 

func (c *Client) CreateBucketFork(ctx context.Context, source, target string, opts ...func(*s3.Options)) (*s3.CreateBucketOutput, error)

CreateBucketFork creates a fork of the source bucket named target.

If you want to specify an exact snapshot version to fork from, use tigrisheaders.WithSnapshotVersion.

Example 
package main

import (
	"context"
	"log"

	storage "github.com/tigrisdata/storage-go"

	_ "github.com/joho/godotenv/autoload"
)

func main() {
	ctx := context.Background()

	client, err := storage.New(ctx)
	if err != nil {
		log.Fatal(err)
	}

	// Creates a new bucket "my-bucket-fork" as a fork of "my-bucket"
	output, err := client.CreateBucketFork(ctx, "my-bucket", "my-bucket-fork")
	if err != nil {
		log.Fatal(err)
	}
	_ = output
}

func (*Client) CreateBucketSnapshot 

func (c *Client) CreateBucketSnapshot(ctx context.Context, description string, in *s3.CreateBucketInput, opts ...func(*s3.Options)) (*CreateBucketSnapshotOutput, error)

CreateBucketSnapshot creates a snapshot with the given description for a bucket. The returned output carries the snapshot version in SnapshotVersion.

Example 
package main

import (
	"context"
	"log"

	"github.com/aws/aws-sdk-go-v2/aws"
	"github.com/aws/aws-sdk-go-v2/service/s3"

	storage "github.com/tigrisdata/storage-go"

	_ "github.com/joho/godotenv/autoload"
)

func main() {
	ctx := context.Background()

	client, err := storage.New(ctx)
	if err != nil {
		log.Fatal(err)
	}

	// Create a snapshot with a description
	output, err := client.CreateBucketSnapshot(ctx, "Initial backup", &s3.CreateBucketInput{
		Bucket: aws.String("my-bucket"),
	})
	if err != nil {
		log.Fatal(err)
	}
	_ = output
}

func (*Client) CreateBucketWithSoftDelete added in v0.8.0 

func (c *Client) CreateBucketWithSoftDelete(ctx context.Context, in *CreateBucketWithSoftDeleteInput, optFns ...func(*s3.Options)) (*s3.CreateBucketOutput, error)

CreateBucketWithSoftDelete creates a bucket with soft delete enabled. Deleting an object or the bucket then moves it into a recoverable soft-deleted state for the retention window instead of removing it immediately.

See Tigris documentation1 for more information.

Example 
package main

import (
	"context"
	"log"

	"github.com/aws/aws-sdk-go-v2/aws"
	"github.com/aws/aws-sdk-go-v2/service/s3"

	storage "github.com/tigrisdata/storage-go"

	_ "github.com/joho/godotenv/autoload"
)

func main() {
	ctx := context.Background()

	client, err := storage.New(ctx)
	if err != nil {
		log.Fatal(err) // handle the error here
	}

	// Create a bucket with the default 7-day soft delete retention window.
	_, err = client.CreateBucketWithSoftDelete(ctx, &storage.CreateBucketWithSoftDeleteInput{
		CreateBucketInput: &s3.CreateBucketInput{
			Bucket: aws.String("my-bucket"),
		},
	})
	if err != nil {
		log.Fatal(err) // handle the error here
	}

	// Create a bucket with a custom 30-day retention window.
	_, err = client.CreateBucketWithSoftDelete(ctx, &storage.CreateBucketWithSoftDeleteInput{
		CreateBucketInput: &s3.CreateBucketInput{
			Bucket: aws.String("my-other-bucket"),
		},
		RetentionDays: 30,
	})
	if err != nil {
		log.Fatal(err) // handle the error here
	}
}

func (*Client) CreateSnapshotEnabledBucket 

func (c *Client) CreateSnapshotEnabledBucket(ctx context.Context, in *s3.CreateBucketInput, opts ...func(*s3.Options)) (*s3.CreateBucketOutput, error)

CreateSnapshotEnabledBucket creates a new bucket with the ability to take snapshots and fork the contents of it.

Example 
package main

import (
	"context"
	"log"

	"github.com/aws/aws-sdk-go-v2/aws"
	"github.com/aws/aws-sdk-go-v2/service/s3"

	storage "github.com/tigrisdata/storage-go"

	_ "github.com/joho/godotenv/autoload"
)

func main() {
	ctx := context.Background()

	client, err := storage.New(ctx)
	if err != nil {
		log.Fatal(err)
	}

	// Create a bucket with snapshot support enabled
	output, err := client.CreateSnapshotEnabledBucket(ctx, &s3.CreateBucketInput{
		Bucket: aws.String("my-bucket"),
	})
	if err != nil {
		log.Fatal(err)
	}
	_ = output
}

func (*Client) ForceDeleteBucket added in v0.8.0 

func (c *Client) ForceDeleteBucket(ctx context.Context, in *s3.DeleteBucketInput, opts ...func(*s3.Options)) (*s3.DeleteBucketOutput, error)

ForceDeleteBucket deletes a bucket even when it is not empty.

If the bucket has soft delete enabled, it is moved to a recoverable soft-deleted state for the retention window instead of being permanently removed; use RestoreBucket to recover it. Otherwise the bucket and its contents are permanently deleted.

This is a dangerous operation. Do not use this unless you are aware of the consequences of your actions. Support will not be able to help you recover any buckets or objects deleted in this way.

See Tigris documentation1 for more information.

Example 
package main

import (
	"context"
	"log"

	"github.com/aws/aws-sdk-go-v2/aws"
	"github.com/aws/aws-sdk-go-v2/service/s3"

	storage "github.com/tigrisdata/storage-go"

	_ "github.com/joho/godotenv/autoload"
)

func main() {
	ctx := context.Background()

	client, err := storage.New(ctx)
	if err != nil {
		log.Fatal(err) // handle the error here
	}

	// Delete a bucket even if it is not empty. If soft delete is enabled on the
	// bucket, it becomes recoverable with RestoreBucket; otherwise it is removed.
	_, err = client.ForceDeleteBucket(ctx, &s3.DeleteBucketInput{
		Bucket: aws.String("my-bucket"),
	})
	if err != nil {
		log.Fatal(err) // handle the error here
	}
}

func (*Client) HeadBucketForkOrSnapshot 

func (c *Client) HeadBucketForkOrSnapshot(ctx context.Context, in *s3.HeadBucketInput, opts ...func(*s3.Options)) (*HeadBucketForkOrSnapshotOutput, error)

HeadBucketForkOrSnapshot fetches the fork/snapshot metadata for a bucket.

For more information, see the Tigris documentation1.

Example 
package main

import (
	"context"
	"log"

	"github.com/aws/aws-sdk-go-v2/aws"
	"github.com/aws/aws-sdk-go-v2/service/s3"

	storage "github.com/tigrisdata/storage-go"

	_ "github.com/joho/godotenv/autoload"
)

func main() {
	ctx := context.Background()

	client, err := storage.New(ctx)
	if err != nil {
		log.Fatal(err)
	}

	// Get fork/snapshot metadata for a bucket
	info, err := client.HeadBucketForkOrSnapshot(ctx, &s3.HeadBucketInput{
		Bucket: aws.String("my-bucket"),
	})
	if err != nil {
		log.Fatal(err)
	}

	_ = info.SnapshotsEnabled     // true if snapshots are enabled
	_ = info.SourceBucket         // The bucket this was forked from
	_ = info.SourceBucketSnapshot // The snapshot this was forked from
	_ = info.IsForkParent         // true if there are forks of this bucket
}

func (*Client) ListBucketSnapshots 

func (c *Client) ListBucketSnapshots(ctx context.Context, bucketName string, opts ...func(*s3.Options)) (*s3.ListBucketsOutput, error)

ListBucketSnapshots lists the snapshots for a bucket.

For more information, see the Tigris documentation1.

Example 
package main

import (
	"context"
	"log"

	storage "github.com/tigrisdata/storage-go"

	_ "github.com/joho/godotenv/autoload"
)

func main() {
	ctx := context.Background()

	client, err := storage.New(ctx)
	if err != nil {
		log.Fatal(err)
	}

	// List all snapshots for a bucket
	snapshots, err := client.ListBucketSnapshots(ctx, "my-bucket")
	if err != nil {
		log.Fatal(err)
	}
	_ = snapshots
}

func (*Client) ListSoftDeletedBuckets added in v0.8.0 

func (c *Client) ListSoftDeletedBuckets(ctx context.Context, in *ListSoftDeletedBucketsInput) (*ListSoftDeletedBucketsOutput, error)

ListSoftDeletedBuckets lists the soft-deleted buckets in the account.

This issues a bucket listing with the OnlyDeleted query parameter so the server returns only soft-deleted buckets, each enriched with its retention window — a field the standard S3 SDK does not surface. Use the returned Name with RestoreBucket to recover a bucket before its window expires. A nil input lists the first page with the server default page size.

This method uses a Tigris endpoint that the S3 SDK cannot express, so it sends a signed request directly and does not accept s3.Options functions. Options such as tigrisheaders.WithHeader have no effect here.

See Tigris documentation1 for more information.

Example 
package main

import (
	"context"
	"log"

	storage "github.com/tigrisdata/storage-go"

	_ "github.com/joho/godotenv/autoload"
)

func main() {
	ctx := context.Background()

	client, err := storage.New(ctx)
	if err != nil {
		log.Fatal(err) // handle the error here
	}

	// List the soft-deleted buckets in the account.
	listed, err := client.ListSoftDeletedBuckets(ctx, nil)
	if err != nil {
		log.Fatal(err) // handle the error here
	}

	for _, bucket := range listed.Buckets {
		_ = bucket.Name          // bucket to restore with RestoreBucket
		_ = bucket.RetentionDays // the configured window, not the time left
	}
}

func (*Client) ListSoftDeletedObjects added in v0.8.0 

func (c *Client) ListSoftDeletedObjects(ctx context.Context, in *ListSoftDeletedObjectsInput) (*ListSoftDeletedObjectsOutput, error)

ListSoftDeletedObjects lists the soft-deleted object versions in a bucket.

This issues a versions listing with the X-Tigris-Soft-Delete header so the server returns soft-deleted versions enriched with their original size, ETag, and a SoftDeleted flag — fields the standard S3 SDK does not surface on delete markers. Use the returned VersionID with RestoreSoftDeletedObject to recover a version or PermanentlyDeleteObject to purge it.

This method uses a Tigris endpoint that the S3 SDK cannot express, so it sends a signed request directly and does not accept s3.Options functions. Options such as tigrisheaders.WithHeader have no effect here.

See Tigris documentation1 for more information.

Example 
package main

import (
	"context"
	"log"

	storage "github.com/tigrisdata/storage-go"

	_ "github.com/joho/godotenv/autoload"
)

func main() {
	ctx := context.Background()

	client, err := storage.New(ctx)
	if err != nil {
		log.Fatal(err) // handle the error here
	}

	// List the soft-deleted object versions in a bucket.
	listed, err := client.ListSoftDeletedObjects(ctx, &storage.ListSoftDeletedObjectsInput{
		Bucket: "my-bucket",
	})
	if err != nil {
		log.Fatal(err) // handle the error here
	}

	for _, obj := range listed.Objects {
		_ = obj.Key          // object key
		_ = obj.VersionID    // version to restore or permanently delete
		_ = obj.Size         // original size in bytes
		_ = obj.LastModified // time the object was soft-deleted
	}
}

func (*Client) PermanentlyDeleteObject added in v0.8.0 

func (c *Client) PermanentlyDeleteObject(ctx context.Context, bucket, key, versionID string, opts ...func(*s3.Options)) (*s3.DeleteObjectOutput, error)

PermanentlyDeleteObject permanently removes a specific soft-deleted object version, bypassing the retention window. The version is gone for good and cannot be restored afterwards.

versionID identifies the soft-deleted version to purge, as returned by ListSoftDeletedObjects, and is required: an empty versionID would target the latest version and create a new soft-delete marker rather than purging a version, the opposite of this method's intent. For a versioned bucket the value is the version ID of the object. For a regular bucket it is the last-modified time of the object as of the moment it was deleted. Both are nanoseconds since the Unix epoch, but treat the value as opaque and pass the VersionID from ListSoftDeletedObjects unchanged.

This is a dangerous operation. Do not use this unless you are aware of the consequences of your actions. Support will not be able to help you recover any buckets or objects deleted in this way.

See Tigris documentation1 for more information.

func (*Client) RenameObject 

func (c *Client) RenameObject(ctx context.Context, in *s3.CopyObjectInput, opts ...func(*s3.Options)) (*s3.CopyObjectOutput, error)

RenameObject performs an in-place rename of objects instead of copying the data.

For more information, see the Tigris documentation1.

Example 
package main

import (
	"context"
	"log"

	"github.com/aws/aws-sdk-go-v2/aws"
	"github.com/aws/aws-sdk-go-v2/service/s3"

	storage "github.com/tigrisdata/storage-go"

	_ "github.com/joho/godotenv/autoload"
)

func main() {
	ctx := context.Background()

	client, err := storage.New(ctx)
	if err != nil {
		log.Fatal(err)
	}

	// Rename an object in-place without copying data
	_, err = client.RenameObject(ctx, &s3.CopyObjectInput{
		Bucket:     aws.String("my-bucket"),
		CopySource: aws.String("my-bucket/old-name.txt"),
		Key:        aws.String("new-name.txt"),
	})
	if err != nil {
		log.Fatal(err)
	}
}

func (*Client) RestoreBucket added in v0.8.0 

func (c *Client) RestoreBucket(ctx context.Context, in *RestoreBucketInput) (*RestoreBucketOutput, error)

RestoreBucket restores a soft-deleted bucket, recovering it and its contents before the retention window expires.

This method uses a Tigris endpoint that the S3 SDK cannot express, so it sends a signed request directly and does not accept s3.Options functions. Options such as tigrisheaders.WithHeader have no effect here.

See Tigris documentation1 for more information.

Example 
package main

import (
	"context"
	"log"

	storage "github.com/tigrisdata/storage-go"

	_ "github.com/joho/godotenv/autoload"
)

func main() {
	ctx := context.Background()

	client, err := storage.New(ctx)
	if err != nil {
		log.Fatal(err) // handle the error here
	}

	// Restore a soft-deleted bucket before its retention window expires.
	_, err = client.RestoreBucket(ctx, &storage.RestoreBucketInput{
		Bucket: "my-bucket",
	})
	if err != nil {
		log.Fatal(err) // handle the error here
	}
}

func (*Client) RestoreSoftDeletedObject added in v0.8.0 

func (c *Client) RestoreSoftDeletedObject(ctx context.Context, in *RestoreSoftDeletedObjectInput) (*RestoreSoftDeletedObjectOutput, error)

RestoreSoftDeletedObject restores a soft-deleted object, undoing a delete before its retention window expires.

This method uses a Tigris endpoint that the S3 SDK cannot express, so it sends a signed request directly and does not accept s3.Options functions. Options such as tigrisheaders.WithHeader have no effect here.

See Tigris documentation1 for more information.

Example 
package main

import (
	"context"
	"log"

	storage "github.com/tigrisdata/storage-go"

	_ "github.com/joho/godotenv/autoload"
)

func main() {
	ctx := context.Background()

	client, err := storage.New(ctx)
	if err != nil {
		log.Fatal(err) // handle the error here
	}

	// Restore the most recent soft-deleted version of an object.
	_, err = client.RestoreSoftDeletedObject(ctx, &storage.RestoreSoftDeletedObjectInput{
		Bucket: "my-bucket",
		Key:    "my-key",
	})
	if err != nil {
		log.Fatal(err) // handle the error here
	}

	// Restore a specific soft-deleted version.
	_, err = client.RestoreSoftDeletedObject(ctx, &storage.RestoreSoftDeletedObjectInput{
		Bucket:    "my-bucket",
		Key:       "my-key",
		VersionID: "1775929768707198086",
	})
	if err != nil {
		log.Fatal(err) // handle the error here
	}
}

func (*Client) S3 added in v0.7.0 

func (c *Client) S3() *s3.Client

S3 returns the underlying S3 client.

func (*Client) SetBucketSoftDelete added in v0.8.0 

func (c *Client) SetBucketSoftDelete(ctx context.Context, in *SetBucketSoftDeleteInput) (*SetBucketSoftDeleteOutput, error)

SetBucketSoftDelete enables or disables soft delete on an existing bucket.

This method uses a Tigris endpoint that the S3 SDK cannot express, so it sends a signed request directly and does not accept s3.Options functions. Options such as tigrisheaders.WithHeader have no effect here.

See Tigris documentation1 for more information.

Example 
package main

import (
	"context"
	"log"

	storage "github.com/tigrisdata/storage-go"

	_ "github.com/joho/godotenv/autoload"
)

func main() {
	ctx := context.Background()

	client, err := storage.New(ctx)
	if err != nil {
		log.Fatal(err) // handle the error here
	}

	// Enable soft delete on an existing bucket with a 30-day retention window.
	_, err = client.SetBucketSoftDelete(ctx, &storage.SetBucketSoftDeleteInput{
		Bucket:        "my-bucket",
		Enabled:       true,
		RetentionDays: 30,
	})
	if err != nil {
		log.Fatal(err) // handle the error here
	}

	// Disable soft delete on an existing bucket.
	_, err = client.SetBucketSoftDelete(ctx, &storage.SetBucketSoftDeleteInput{
		Bucket:  "my-bucket",
		Enabled: false,
	})
	if err != nil {
		log.Fatal(err) // handle the error here
	}
}

type CreateBucketSnapshotOutput added in v0.7.0 

type CreateBucketSnapshotOutput struct {
	*s3.CreateBucketOutput

	// SnapshotVersion is the version identifier of the snapshot just created.
	// Empty if the server did not return a version header.
	SnapshotVersion string
}

CreateBucketSnapshotOutput is the response from CreateBucketSnapshot. It wraps the underlying s3.CreateBucketOutput and surfaces the snapshot version that Tigris returns in the X-Tigris-Snapshot-Version response header.

type CreateBucketWithSoftDeleteInput added in v0.8.0 

type CreateBucketWithSoftDeleteInput struct {
	// CreateBucketInput carries the standard S3 create-bucket parameters. Required.
	*s3.CreateBucketInput

	// RetentionDays sets the soft delete retention window in days. Use 0 for the
	// default 7-day window, or a value between 7 and 90 for a custom window.
	// Values outside the 7-90 range are rejected by the server.
	RetentionDays int
}

CreateBucketWithSoftDeleteInput is the input for a CreateBucketWithSoftDelete request.

type HeadBucketForkOrSnapshotOutput 

type HeadBucketForkOrSnapshotOutput struct {
	SnapshotsEnabled     bool   // true if snapshots are enabled, otherwise false.
	SourceBucket         string // The name of the bucket this bucket was forked from.
	SourceBucketSnapshot string // The snapshot this bucket was forked from.
	IsForkParent         bool   // true if there are forks of this bucket, otherwise false.
}

HeadBucketForkOrSnapshotOutput records the fork/snapshot metadata for a bucket.

type ListSoftDeletedBucketsInput added in v0.8.0 

type ListSoftDeletedBucketsInput struct {
	// ContinuationToken continues a truncated listing from NextContinuationToken. Optional.
	ContinuationToken string
	// MaxBuckets limits the number of buckets returned. Optional; 0 uses the server default.
	MaxBuckets int32
}

ListSoftDeletedBucketsInput is the input for a ListSoftDeletedBuckets request.

type ListSoftDeletedBucketsOutput added in v0.8.0 

type ListSoftDeletedBucketsOutput struct {
	// Buckets is the list of soft-deleted buckets.
	Buckets []SoftDeletedBucket
	// IsTruncated reports whether more results are available beyond this page.
	IsTruncated bool
	// NextContinuationToken is the token to pass as ContinuationToken for the next page.
	NextContinuationToken string
}

ListSoftDeletedBucketsOutput is the response from a ListSoftDeletedBuckets request.

type ListSoftDeletedObjectsInput added in v0.8.0 

type ListSoftDeletedObjectsInput struct {
	// Bucket is the name of the bucket to list. Required.
	Bucket string
	// Prefix limits the response to keys that begin with the prefix. Optional.
	Prefix string
	// KeyMarker continues a truncated listing from NextKeyMarker. Optional.
	KeyMarker string
	// VersionIDMarker continues a truncated listing from NextVersionIDMarker. Optional.
	VersionIDMarker string
	// MaxKeys limits the number of versions returned. Optional; 0 uses the server default.
	MaxKeys int32
}

ListSoftDeletedObjectsInput is the input for a ListSoftDeletedObjects request.

type ListSoftDeletedObjectsOutput added in v0.8.0 

type ListSoftDeletedObjectsOutput struct {
	// Objects is the list of soft-deleted object versions.
	Objects []SoftDeletedObject
	// IsTruncated reports whether more results are available beyond this page.
	IsTruncated bool
	// NextKeyMarker is the key marker to pass as KeyMarker for the next page.
	NextKeyMarker string
	// NextVersionIDMarker is the version-id marker to pass as VersionIDMarker for the next page.
	NextVersionIDMarker string
}

ListSoftDeletedObjectsOutput is the response from a ListSoftDeletedObjects request.

type Option 

type Option func(o *Options)

Option is a functional option for configuring the Tigris client.

func WithAccessKeypair 

func WithAccessKeypair(accessKeyID, secretAccessKey string) Option

WithAccessKeypair lets you specify a custom access key and secret access key for interfacing with Tigris.

This is useful when you need to load environment variables from somewhere other than the default AWS configuration path.

func WithEndpoint 

func WithEndpoint(endpoint string) Option

WithEndpoint sets a custom endpoint for connecting to Tigris.

This allows you to connect to a custom Tigris endpoint instead of the default global endpoint. Use this for:

  • Using a custom proxy or gateway
  • Testing against local development endpoints

For most use cases, consider using WithGlobalEndpoint or WithFlyEndpoint instead.

func WithFlyEndpoint 

func WithFlyEndpoint() Option

WithFlyEndpoint lets you connect to Tigris' fly.io optimized endpoint.

If you are deployed to fly.io, this zero-rates your traffic to Tigris.

If you are not deployed to fly.io, please use WithGlobalEndpoint instead.

func WithGlobalEndpoint 

func WithGlobalEndpoint() Option

WithGlobalEndpoint lets you connect to Tigris' globally available endpoint.

If you are deployed to fly.io, please use WithFlyEndpoint instead.

func WithPathStyle 

func WithPathStyle(enabled bool) Option

WithPathStyle configures whether to use path-style addressing for S3 requests.

By default, Tigris uses virtual-hosted-style addressing (e.g., https://bucket.t3.storage.dev). Path-style addressing (e.g., https://t3.storage.dev/bucket) may be needed for:

  • Compatibility with older S3 clients that don't support virtual-hosted-style
  • Working through certain proxies or load balancers that don't support virtual-hosted-style
  • Local development environments with custom DNS setups

Enable this only if you encounter issues with the default virtual-hosted-style addressing.

func WithRegion 

func WithRegion(region string) Option

WithRegion lets you statically specify a region for interacting with Tigris.

You will almost certainly never need this. This is here for development usecases where the default region is not "auto".

type Options 

type Options struct {
	BaseEndpoint string
	Region       string
	UsePathStyle bool

	AccessKeyID     string
	SecretAccessKey string
}

Options is the set of options that can be configured for the Tigris client.

type RestoreBucketInput added in v0.8.0 

type RestoreBucketInput struct {
	// Bucket is the name of the soft-deleted bucket to restore. Required.
	Bucket string
}

RestoreBucketInput is the input for a RestoreBucket request.

type RestoreBucketOutput added in v0.8.0 

type RestoreBucketOutput struct{}

RestoreBucketOutput is the response from a RestoreBucket request.

type RestoreSoftDeletedObjectInput added in v0.8.0 

type RestoreSoftDeletedObjectInput struct {
	// Bucket is the name of the bucket containing the object. Required.
	Bucket string
	// Key is the object key to restore. Required.
	Key string
	// VersionID restores a specific soft-deleted version, as returned by
	// ListSoftDeletedObjects. For a versioned bucket the value is the version ID
	// of the object. For a regular bucket it is the last-modified time of the
	// object as of the moment it was deleted. Both are nanoseconds since the Unix
	// epoch, but treat the value as opaque and pass it through from
	// ListSoftDeletedObjects unchanged. Optional; empty restores the most recent
	// soft-deleted version.
	VersionID string
}

RestoreSoftDeletedObjectInput is the input for a RestoreSoftDeletedObject request.

type RestoreSoftDeletedObjectOutput added in v0.8.0 

type RestoreSoftDeletedObjectOutput struct{}

RestoreSoftDeletedObjectOutput is the response from a RestoreSoftDeletedObject request.

type SetBucketSoftDeleteInput added in v0.8.0 

type SetBucketSoftDeleteInput struct {
	// Bucket is the name of the bucket to configure. Required.
	Bucket string
	// Enabled turns soft delete on or off for the bucket.
	Enabled bool
	// RetentionDays sets the soft delete retention window in days when enabling.
	// Use 0 for the default 7-day window, or a value between 7 and 90 for a custom
	// window. Ignored when disabling.
	RetentionDays int
}

SetBucketSoftDeleteInput is the input for a SetBucketSoftDelete request.

type SetBucketSoftDeleteOutput added in v0.8.0 

type SetBucketSoftDeleteOutput struct{}

SetBucketSoftDeleteOutput is the response from a SetBucketSoftDelete request.

type SoftDeletedBucket added in v0.8.0 

type SoftDeletedBucket struct {
	// Name is the bucket name. It stays reserved while the bucket is
	// soft-deleted.
	Name string
	// InitialCreatedDate is the time the bucket was first created.
	InitialCreatedDate time.Time
	// CreationDate is the time the bucket was most recently modified. It is the
	// same as InitialCreatedDate when the bucket was never modified.
	CreationDate time.Time
	// RetentionDays is the soft delete retention window in days. The bucket is
	// permanently removed once the window expires.
	RetentionDays int
}

SoftDeletedBucket describes a single soft-deleted bucket returned by ListSoftDeletedBuckets.

type SoftDeletedObject added in v0.8.0 

type SoftDeletedObject struct {
	// Key is the object key.
	Key string
	// VersionID identifies this soft-deleted version. Use it with
	// RestoreSoftDeletedObject or PermanentlyDeleteObject.
	VersionID string
	// Size is the size of the object in bytes.
	Size int64
	// ETag is the entity tag of the object.
	ETag string
	// SoftDeleted reports whether the version is soft-deleted.
	SoftDeleted bool
	// LastModified is the time the object was soft-deleted.
	LastModified time.Time
}

SoftDeletedObject describes a single soft-deleted object version returned by ListSoftDeletedObjects.

Source Files

View all Source files

Directories

Path Synopsis
Package tigrisheaders contains Tigris-specific header helpers for the AWS S3 SDK and helpers for interacting with Tigris.
 Package tigrisheaders contains Tigris-specific header helpers for the AWS S3 SDK and helpers for interacting with Tigris.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.