storage

package module
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Jan 15, 2026 License: MIT Imports: 10 Imported by: 0

README

Tigris Storage SDK for Go

Looking for TypeScript? The Tigris Storage TypeScript SDK is available at github.com/tigrisdata/storage or on NPM as @tigrisdata/storage.

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 two main packages:

  • storage - The main package containing the Tigris client with S3-compatible methods plus Tigris-specific features like bucket forking, snapshots, and object renaming.
  • tigrisheaders - Lower-level helpers for setting Tigris-specific HTTP headers on S3 API calls.

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"),
})
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

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"),
})

Using the tigrisheaders Package

The tigrisheaders package provides lower-level helpers for setting Tigris-specific HTTP headers. These can be used directly with S3 client operations.

Static Replication Regions

Control which regions your objects are replicated to:

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

// Replicate to specific regions
_, err := client.PutObject(ctx, &s3.PutObjectInput{
    Bucket: aws.String("my-bucket"),
    Key:    aws.String("file.txt"),
    Body:   bytes.NewReader(data),
}, tigrisheaders.WithStaticReplicationRegions([]tigrisheaders.Region{
    tigrisheaders.FRA, // Frankfurt
    tigrisheaders.SJC, // San Jose
}))

Available regions:

  • FRA - Frankfurt, Germany
  • GRU - São Paulo, Brazil
  • HKG - Hong Kong, China
  • IAD - Ashburn, Virginia, USA
  • JNB - Johannesburg, South Africa
  • LHR - London, UK
  • MAD - Madrid, Spain
  • NRT - Tokyo (Narita), Japan
  • ORD - Chicago, Illinois, USA
  • SIN - Singapore
  • SJC - San Jose, California, USA
  • SYD - Sydney, Australia
  • Europe - European datacenters
  • USA - American datacenters
Query Metadata

Filter objects in a ListObjectsV2 request with a SQL-like WHERE clause:

_, err := client.ListObjectsV2(ctx, &s3.ListObjectsV2Input{
    Bucket: aws.String("my-bucket"),
}, tigrisheaders.WithQuery("metadata.user_id = '123'"))
Conditional Operations

Perform operations based on object state:

// Create object only if it doesn't exist
_, err := client.PutObject(ctx, input,
    tigrisheaders.WithCreateObjectIfNotExists())

// Only proceed if ETag matches
_, err := client.PutObject(ctx, input,
    tigrisheaders.WithIfEtagMatches("\"abc123\""))

// Only proceed if modified since date
_, err := client.GetObject(ctx, input,
    tigrisheaders.WithModifiedSince(time.Now().Add(-24 * time.Hour)))

// Only proceed if unmodified since date
_, err := client.GetObject(ctx, input,
    tigrisheaders.WithUnmodifiedSince(time.Now().Add(-24 * time.Hour)))

// Compare-and-swap (skip cache, read from designated region)
_, err := client.GetObject(ctx, input,
    tigrisheaders.WithCompareAndSwap())
Snapshot Operations

Work with specific snapshot versions:

// List objects from a specific snapshot
_, err := client.ListObjectsV2(ctx, &s3.ListObjectsV2Input{
    Bucket: aws.String("my-bucket"),
}, tigrisheaders.WithSnapshotVersion("snapshot-id"))

// Get object from a specific snapshot
_, err := client.GetObject(ctx, &s3.GetObjectInput{
    Bucket: aws.String("my-bucket"),
    Key:    aws.String("file.txt"),
}, tigrisheaders.WithSnapshotVersion("snapshot-id"))
Custom Headers

Set arbitrary HTTP headers on requests:

_, err := client.PutObject(ctx, input,
    tigrisheaders.WithHeader("X-Custom-Header", "value"))

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 (
	GlobalEndpoint = "https://t3.storage.dev"
	FlyEndpoint    = "https://fly.storage.tigris.dev"
)

Variables

This section is empty.

Functions

This section is empty.

Types

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) 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)) (*s3.CreateBucketOutput, error)

CreateBucketSnapshot creates a snapshot with the given description for a bucket.

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) 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) 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) 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)
	}
}

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

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.