datastore

package module
v1.4.1 Latest Latest
Warning

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

 Go to latest Published: Jan 25, 2018 License: MIT Imports: 8 Imported by: 0

README

go-datastore

standard-readme compliant GoDoc

key-value datastore interfaces

datastore is a generic layer of abstraction for data store and database access. It is a simple API with the aim to enable application development in a datastore-agnostic way, allowing datastores to be swapped seamlessly without changing application code. Thus, one can leverage different datastores with different strengths without committing the application to one datastore throughout its lifetime.

In addition, grouped datastores significantly simplify interesting data access patterns (such as caching and sharding).

Based on datastore.py.

Documentation

https://godoc.org/github.com/ipfs/go-datastore

Contribute

Feel free to join in. All welcome. Open an issue!

This repository falls under the IPFS Code of Conduct.

Want to hack on IPFS?

License

MIT

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var ErrBatchUnsupported = errors.New("this datastore does not support batching")
View Source 
var ErrInvalidType = errors.New("datastore: invalid type error")

ErrInvalidType is returned by Put when a given value is incopatible with the type the datastore supports. This means a conversion (or serialization) is needed beforehand.

View Source 
var ErrNotFound = errors.New("datastore: key not found")

ErrNotFound is returned by Get, Has, and Delete when a datastore does not map the given key to a value.

Functions

func GetBackedHas 

func GetBackedHas(ds Datastore, key Key) (bool, error)

GetBackedHas provides a default Datastore.Has implementation. It exists so Datastore.Has implementations can use it, like so: 

func (*d SomeDatastore) Has(key Key) (exists bool, err error) {
  return GetBackedHas(d, key)
}

func NamespaceType 

func NamespaceType(namespace string) string

NamespaceType is the first component of a namespace. `foo` in `foo:bar`

func NamespaceValue 

func NamespaceValue(namespace string) string

NamespaceValue returns the last component of a namespace. `baz` in `f:b:baz`

Types

type Batch 

type Batch interface {
	Put(key Key, val interface{}) error

	Delete(key Key) error

	Commit() error
}

func NewBasicBatch 

func NewBasicBatch(ds Datastore) Batch

type Batching 

type Batching interface {
	Datastore

	Batch() (Batch, error)
}

type CheckedDatastore 

type CheckedDatastore interface {
	Datastore

	Check() error
}

CheckedDatastore is an interface that should be implemented by datastores which may need checking on-disk data integrity.

type Datastore 

type Datastore interface {
	// Put stores the object `value` named by `key`.
	//
	// The generalized Datastore interface does not impose a value type,
	// allowing various datastore middleware implementations (which do not
	// handle the values directly) to be composed together.
	//
	// Ultimately, the lowest-level datastore will need to do some value checking
	// or risk getting incorrect values. It may also be useful to expose a more
	// type-safe interface to your application, and do the checking up-front.
	Put(key Key, value interface{}) error

	// Get retrieves the object `value` named by `key`.
	// Get will return ErrNotFound if the key is not mapped to a value.
	Get(key Key) (value interface{}, err error)

	// Has returns whether the `key` is mapped to a `value`.
	// In some contexts, it may be much cheaper only to check for existence of
	// a value, rather than retrieving the value itself. (e.g. HTTP HEAD).
	// The default implementation is found in `GetBackedHas`.
	Has(key Key) (exists bool, err error)

	// Delete removes the value for given `key`.
	Delete(key Key) error

	// Query searches the datastore and returns a query result. This function
	// may return before the query actually runs. To wait for the query:
	//
	//   result, _ := ds.Query(q)
	//
	//   // use the channel interface; result may come in at different times
	//   for entry := range result.Next() { ... }
	//
	//   // or wait for the query to be completely done
	//   entries, _ := result.Rest()
	//   for entry := range entries { ... }
	//
	Query(q query.Query) (query.Results, error)
}

Datastore represents storage for any key-value pair.

Datastores are general enough to be backed by all kinds of different storage: in-memory caches, databases, a remote datastore, flat files on disk, etc.

The general idea is to wrap a more complicated storage facility in a simple, uniform interface, keeping the freedom of using the right tools for the job. In particular, a Datastore can aggregate other datastores in interesting ways, like sharded (to distribute load) or tiered access (caches before databases).

While Datastores should be written general enough to accept all sorts of values, some implementations will undoubtedly have to be specific (e.g. SQL databases where fields should be decomposed into columns), particularly to support queries efficiently. Moreover, certain datastores may enforce certain types of values (e.g. requiring an io.Reader, a specific struct, etc) or serialization formats (JSON, Protobufs, etc).

IMPORTANT: No Datastore should ever Panic! This is a cross-module interface, and thus it should behave predictably and handle exceptional conditions with proper error reporting. Thus, all Datastore calls may return errors, which should be checked by callers.

type GCDatastore 

type GCDatastore interface {
	Datastore

	CollectGarbage() error
}

GCDatastore is an interface that should be implemented by datastores which don't free disk space by just removing data from them

type Key 

type Key struct {
	// contains filtered or unexported fields
}

A Key represents the unique identifier of an object. Our Key scheme is inspired by file systems and Google App Engine key model.

Keys are meant to be unique across a system. Keys are hierarchical, incorporating more and more specific namespaces. Thus keys can be deemed 'children' or 'ancestors' of other keys:: 

Key("/Comedy")
Key("/Comedy/MontyPython")

Also, every namespace can be parametrized to embed relevant object information. For example, the Key `name` (most specific namespace) could include the object type:: 

Key("/Comedy/MontyPython/Actor:JohnCleese")
Key("/Comedy/MontyPython/Sketch:CheeseShop")
Key("/Comedy/MontyPython/Sketch:CheeseShop/Character:Mousebender")

func EntryKeys 

func EntryKeys(e []dsq.Entry) []Key

EntryKeys

func KeyWithNamespaces 

func KeyWithNamespaces(ns []string) Key

KeyWithNamespaces constructs a key out of a namespace slice.

func NewKey 

func NewKey(s string) Key

NewKey constructs a key from string. it will clean the value.

func RandomKey 

func RandomKey() Key

RandomKey returns a randomly (uuid) generated key. 

RandomKey()
NewKey("/f98719ea086343f7b71f32ea9d9d521d")

func RawKey 

func RawKey(s string) Key

RawKey creates a new Key without safety checking the input. Use with care.

func (Key) BaseNamespace 

func (k Key) BaseNamespace() string

BaseNamespace returns the "base" namespace of this key (path.Base(filename)) 

NewKey("/Comedy/MontyPython/Actor:JohnCleese").BaseNamespace()
"Actor:JohnCleese"

func (Key) Bytes 

func (k Key) Bytes() []byte

Bytes returns the string value of Key as a []byte

func (Key) Child 

func (k Key) Child(k2 Key) Key

Child returns the `child` Key of this Key. 

NewKey("/Comedy/MontyPython").Child(NewKey("Actor:JohnCleese"))
NewKey("/Comedy/MontyPython/Actor:JohnCleese")

func (Key) ChildString 

func (k Key) ChildString(s string) Key

ChildString returns the `child` Key of this Key -- string helper. 

NewKey("/Comedy/MontyPython").ChildString("Actor:JohnCleese")
NewKey("/Comedy/MontyPython/Actor:JohnCleese")

func (*Key) Clean 

func (k *Key) Clean()

Clean up a Key, using path.Clean.

func (Key) Equal 

func (k Key) Equal(k2 Key) bool

Equal checks equality of two keys

func (Key) Instance 

func (k Key) Instance(s string) Key

Instance returns an "instance" of this type key (appends value to namespace). 

NewKey("/Comedy/MontyPython/Actor").Instance("JohnClesse")
NewKey("/Comedy/MontyPython/Actor:JohnCleese")

func (Key) IsAncestorOf 

func (k Key) IsAncestorOf(other Key) bool

IsAncestorOf returns whether this key is a prefix of `other` 

NewKey("/Comedy").IsAncestorOf("/Comedy/MontyPython")
true

func (Key) IsDescendantOf 

func (k Key) IsDescendantOf(other Key) bool

IsDescendantOf returns whether this key contains another as a prefix. 

NewKey("/Comedy/MontyPython").IsDescendantOf("/Comedy")
true

func (Key) IsTopLevel 

func (k Key) IsTopLevel() bool

IsTopLevel returns whether this key has only one namespace.

func (Key) Less 

func (k Key) Less(k2 Key) bool

Less checks whether this key is sorted lower than another.

func (Key) List 

func (k Key) List() []string

List returns the `list` representation of this Key. 

NewKey("/Comedy/MontyPython/Actor:JohnCleese").List()
["Comedy", "MontyPythong", "Actor:JohnCleese"]

func (Key) MarshalJSON 

func (k Key) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface, keys are represented as JSON strings

func (Key) Name 

func (k Key) Name() string

Name returns the "name" of this key (field of last namespace). 

NewKey("/Comedy/MontyPython/Actor:JohnCleese").Name()
"JohnCleese"

func (Key) Namespaces 

func (k Key) Namespaces() []string

Namespaces returns the `namespaces` making up this Key. 

NewKey("/Comedy/MontyPython/Actor:JohnCleese").Namespaces()
["Comedy", "MontyPython", "Actor:JohnCleese"]

func (Key) Parent 

func (k Key) Parent() Key

Parent returns the `parent` Key of this Key. 

NewKey("/Comedy/MontyPython/Actor:JohnCleese").Parent()
NewKey("/Comedy/MontyPython")

func (Key) Path 

func (k Key) Path() Key

Path returns the "path" of this key (parent + type). 

NewKey("/Comedy/MontyPython/Actor:JohnCleese").Path()
NewKey("/Comedy/MontyPython/Actor")

func (Key) Reverse 

func (k Key) Reverse() Key

Reverse returns the reverse of this Key. 

NewKey("/Comedy/MontyPython/Actor:JohnCleese").Reverse()
NewKey("/Actor:JohnCleese/MontyPython/Comedy")

func (Key) String 

func (k Key) String() string

Strings is the string value of Key

func (Key) Type 

func (k Key) Type() string

Type returns the "type" of this key (value of last namespace). 

NewKey("/Comedy/MontyPython/Actor:JohnCleese").Type()
"Actor"

func (*Key) UnmarshalJSON 

func (k *Key) UnmarshalJSON(data []byte) error

MarshalJSON implements the json.Unmarshaler interface, keys will parse any value specified as a key to a string

type KeySlice 

type KeySlice []Key

KeySlice attaches the methods of sort.Interface to []Key, sorting in increasing order.

func (KeySlice) Len 

func (p KeySlice) Len() int

func (KeySlice) Less 

func (p KeySlice) Less(i, j int) bool

func (KeySlice) Swap 

func (p KeySlice) Swap(i, j int)

type LogBatch 

type LogBatch struct {
	Name string
	// contains filtered or unexported fields
}

LogBatch logs all accesses through the batch.

func (*LogBatch) Commit 

func (d *LogBatch) Commit() (err error)

Commit implements Batch.Commit

func (*LogBatch) Delete 

func (d *LogBatch) Delete(key Key) (err error)

Delete implements Batch.Delete

func (*LogBatch) Put 

func (d *LogBatch) Put(key Key, value interface{}) (err error)

Put implements Batch.Put

type LogDatastore 

type LogDatastore struct {
	Name string
	// contains filtered or unexported fields
}

LogDatastore logs all accesses through the datastore.

func NewLogDatastore 

func NewLogDatastore(ds Datastore, name string) *LogDatastore

NewLogDatastore constructs a log datastore.

func (*LogDatastore) Batch 

func (d *LogDatastore) Batch() (Batch, error)

func (*LogDatastore) Check 

func (d *LogDatastore) Check() error

func (*LogDatastore) Children 

func (d *LogDatastore) Children() []Datastore

Children implements Shim

func (*LogDatastore) Close 

func (d *LogDatastore) Close() error

func (*LogDatastore) CollectGarbage 

func (d *LogDatastore) CollectGarbage() error

func (*LogDatastore) Delete 

func (d *LogDatastore) Delete(key Key) (err error)

Delete implements Datastore.Delete

func (*LogDatastore) Get 

func (d *LogDatastore) Get(key Key) (value interface{}, err error)

Get implements Datastore.Get

func (*LogDatastore) Has 

func (d *LogDatastore) Has(key Key) (exists bool, err error)

Has implements Datastore.Has

func (*LogDatastore) Put 

func (d *LogDatastore) Put(key Key, value interface{}) (err error)

Put implements Datastore.Put

func (*LogDatastore) Query 

func (d *LogDatastore) Query(q dsq.Query) (dsq.Results, error)

Query implements Datastore.Query

func (*LogDatastore) Scrub 

func (d *LogDatastore) Scrub() error

type MapDatastore 

type MapDatastore struct {
	// contains filtered or unexported fields
}

MapDatastore uses a standard Go map for internal storage.

func NewMapDatastore 

func NewMapDatastore() (d *MapDatastore)

NewMapDatastore constructs a MapDatastore

func (*MapDatastore) Batch 

func (d *MapDatastore) Batch() (Batch, error)

func (*MapDatastore) Close 

func (d *MapDatastore) Close() error

func (*MapDatastore) Delete 

func (d *MapDatastore) Delete(key Key) (err error)

Delete implements Datastore.Delete

func (*MapDatastore) Get 

func (d *MapDatastore) Get(key Key) (value interface{}, err error)

Get implements Datastore.Get

func (*MapDatastore) Has 

func (d *MapDatastore) Has(key Key) (exists bool, err error)

Has implements Datastore.Has

func (*MapDatastore) Put 

func (d *MapDatastore) Put(key Key, value interface{}) (err error)

Put implements Datastore.Put

func (*MapDatastore) Query 

func (d *MapDatastore) Query(q dsq.Query) (dsq.Results, error)

Query implements Datastore.Query

type NullDatastore 

type NullDatastore struct {
}

NullDatastore stores nothing, but conforms to the API. Useful to test with.

func NewNullDatastore 

func NewNullDatastore() *NullDatastore

NewNullDatastore constructs a null datastoe

func (*NullDatastore) Batch 

func (d *NullDatastore) Batch() (Batch, error)

func (*NullDatastore) Close 

func (d *NullDatastore) Close() error

func (*NullDatastore) Delete 

func (d *NullDatastore) Delete(key Key) (err error)

Delete implements Datastore.Delete

func (*NullDatastore) Get 

func (d *NullDatastore) Get(key Key) (value interface{}, err error)

Get implements Datastore.Get

func (*NullDatastore) Has 

func (d *NullDatastore) Has(key Key) (exists bool, err error)

Has implements Datastore.Has

func (*NullDatastore) Put 

func (d *NullDatastore) Put(key Key, value interface{}) (err error)

Put implements Datastore.Put

func (*NullDatastore) Query 

func (d *NullDatastore) Query(q dsq.Query) (dsq.Results, error)

Query implements Datastore.Query

type ScrubbedDatastore 

type ScrubbedDatastore interface {
	Datastore

	Scrub() error
}

CheckedDatastore is an interface that should be implemented by datastores which want to provide a mechanism to check data integrity and/or error correction

type Shim 

type Shim interface {
	Datastore

	Children() []Datastore
}

Shim is a datastore which has a child.

type ThreadSafeDatastore 

type ThreadSafeDatastore interface {
	Datastore

	IsThreadSafe()
}

ThreadSafeDatastore is an interface that all threadsafe datastore should implement to leverage type safety checks.

Source Files

View all Source files

Directories

Path Synopsis
Package fs is a simple Datastore implementation that stores keys are directories and files, mirroring the key.
 Package fs is a simple Datastore implementation that stores keys are directories and files, mirroring the key.
Package keytransform introduces a Datastore Shim that transforms keys before passing them to its child.
 Package keytransform introduces a Datastore Shim that transforms keys before passing them to its child.
Package mount provides a Datastore that has other Datastores mounted at various key prefixes.
 Package mount provides a Datastore that has other Datastores mounted at various key prefixes.
Package namespace introduces a namespace Datastore Shim, which basically mounts the entire child datastore under a prefix.
 Package namespace introduces a namespace Datastore Shim, which basically mounts the entire child datastore under a prefix.
Package mount provides a Datastore that has other Datastores mounted at various key prefixes and is threadsafe
 Package mount provides a Datastore that has other Datastores mounted at various key prefixes and is threadsafe

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.