Skip to main content


Operation means a single action that we can do on a storage service.


servicer is used to maintain the storage service.

We use Servicer to create/delete/get/list storages.


storager is the interface for storage service.

We use Storager to maintain objects.

How to initialize a Servicer/Storager?

We have connection string support.

The format of the connection string is (optional parts marked by squared brackets):


  • name: storage name, e.g., bucket name. MUST NOT contain /
  • work_dir: For object storage, it is prefix; for fs, it is directory path. MUST start with / for every storage services.
  • For the enable_feature query string:
    • feature is the feature name defined in toml, and the format SHOULD be exactly the same.
  • For the key=value pairs:
    • If =value is missing, we just ignore the pair. But key= means a pair with a blank value.
    • The key is the pair name defined in toml and the format SHOULD be exactly the same.
    • Or the key is the default pair name prefixed with default_ and followed by pair name described above.
  • If there are multiple pairs with the same key, the first one will be picked.

So a valid connection string could be:

  • s3://bucket_name
  • s3://bucket_name/prefix
  • s3://?credential=hmac:xxxx:xxxx&
  • s3://bucket_name/prefix?credential=hmac:xxxx:xxxx&
  • s3://bucket_name/prefix?enable_virtual_dir&credential=hmac:xxxx:xxxx&
  • fs://
  • fs:///tmp

For more details, take a look at GSP-90 and GSP-700.


To use a service, do not forget to import the corresponding go-service-* package so that the service can be registered in the init function.

import (
_ ""

store, err := services.NewStoragerFromString("fs:///tmp")

Initialize directly with pairs

Alternatively, you can initialize directly with pairs, if you want to

  • use a complex pair that connection string doesn't support yet or is not convenient to write by hand
  • construct pairs from your config format without transforming into the connection string format
  • reduce the overheads of parsing the connection string
import (
_ ""

store, err := services.NewStorager("fs", pairs.WithWorkDir("/tmp"))