A unified storage SDK for Go services that need one client shape across object and blob storage providers. Heavily inspired by files-sdk by Hayden Bleasel
- One API across providers: call
Upload,Download,Head,Exists,Delete,Copy,Move,List,ListAll,Search,URL, andSignedUploadURLagainst any adapter. - Go-native bodies: upload strings, byte slices, readers, files, or custom read closers with the
files.Bodyhelpers. - File handles: bind repeated operations to one key with
client.File("backups/backup.sql"). - Operational controls: configure prefixes, read-only clients, timeouts, retries, hooks, middleware, progress, bulk work, and transfers.
- Provider escape hatch: use
client.Raw()when provider-specific behavior belongs in the native client.
go get github.com/cersho/gofiles-sdkRequires Go 1.26 or newer.
package main
import (
"context"
"fmt"
files "github.com/cersho/gofiles-sdk"
"github.com/cersho/gofiles-sdk/providers/memory"
)
func main() {
ctx := context.Background()
client := files.MustNew(files.Options{Adapter: memory.New(memory.Options{})})
if _, err := client.Upload(ctx, "reports/q1.txt", files.StringBody("revenue: 42"), files.UploadOptions{ContentType: "text/plain"}); err != nil {
panic(err)
}
stored, err := client.Download(ctx, "reports/q1.txt", files.DownloadOptions{})
if err != nil {
panic(err)
}
text, err := stored.Text(ctx)
if err != nil {
panic(err)
}
fmt.Println(text)
// Output: revenue: 42
}Save it as main.go, run go run ., then swap the memory adapter for a cloud provider when you are ready.
Import only the adapter you use:
| Backend | Import path |
|---|---|
| Memory | github.com/cersho/gofiles-sdk/providers/memory |
| Filesystem | github.com/cersho/gofiles-sdk/providers/fs |
| S3 | github.com/cersho/gofiles-sdk/providers/s3 |
| Cloudflare R2 | github.com/cersho/gofiles-sdk/providers/r2 |
| S3-compatible storage | github.com/cersho/gofiles-sdk/providers/s3compatible |
| Appwrite | github.com/cersho/gofiles-sdk/providers/appwrite |
| DigitalOcean Spaces | github.com/cersho/gofiles-sdk/providers/digitaloceanspaces |
| Supabase Storage | github.com/cersho/gofiles-sdk/providers/supabase |
| UploadThing | github.com/cersho/gofiles-sdk/providers/uploadthing |
| Vercel Blob | github.com/cersho/gofiles-sdk/providers/vercelblob |
S3-backed adapters use AWS SDK for Go v2, which is already declared by the module.
Run these commands from the repository root:
bun install
bun run test
bun run build
bun run docs:dev