Skip to main content

Getting started

Your first program​

This program builds an operator, writes a file, reads it back, inspects its metadata, and deletes it. It runs against the in-memory service with no credentials, so you can run it right after installing.

Add the binding and the scheme package for the service you want:

go get github.com/apache/opendal/bindings/go@latest
go get github.com/apache/opendal-go-services/memory
package main

import (
"fmt"
"log"

"github.com/apache/opendal-go-services/memory"
opendal "github.com/apache/opendal/bindings/go"
)

func main() {
// Configure a service, then build an operator from it.
op, err := opendal.NewOperator(memory.Scheme, opendal.OperatorOptions{})
if err != nil {
log.Fatal(err)
}
defer op.Close() // Always close the operator to release resources.

// The same verbs work on every service.
if _, err := op.Write("hello.txt", []byte("Hello, World!")); err != nil {
log.Fatal(err)
}

data, err := op.Read("hello.txt")
if err != nil {
log.Fatal(err)
}
fmt.Printf("read %d bytes: %s\n", len(data), data)

meta, err := op.Stat("hello.txt")
if err != nil {
log.Fatal(err)
}
fmt.Printf("size = %d bytes\n", meta.ContentLength())

if err := op.Delete("hello.txt"); err != nil {
log.Fatal(err)
}
}

Note that Write takes []byte and Read returns []byte. Every method returns an error as its last value — check it instead of expecting a panic.

Point it at a real backend​

Only the service changes; the operations stay identical. To use S3, import its scheme package and pass configuration through OperatorOptions, a map[string]string of configuration keys:

go get github.com/apache/opendal-go-services/s3
import (
"github.com/apache/opendal-go-services/s3"
opendal "github.com/apache/opendal/bindings/go"
)

op, err := opendal.NewOperator(s3.Scheme, opendal.OperatorOptions{
"bucket": "my-bucket",
"region": "us-east-1",
})
if err != nil {
log.Fatal(err)
}
defer op.Close()

if err := op.Write("hello.txt", []byte("Hello from S3!")); err != nil {
log.Fatal(err)
}

Each service is a separate opendal-go-services module, so add the ones you use. The next page, Connecting to your storage, covers configuration and credentials in depth; Services lists every backend and its configuration keys.