datastore.go 5.75 KB
Newer Older
Juan Batiz-Benet's avatar
Juan Batiz-Benet committed
1
package datastore
Juan Batiz-Benet's avatar
Juan Batiz-Benet committed
2 3

import (
Juan Batiz-Benet's avatar
go fmt  
Juan Batiz-Benet committed
4
	"errors"
5
	"time"
6

Jeromy's avatar
Jeromy committed
7
	query "github.com/ipfs/go-datastore/query"
Juan Batiz-Benet's avatar
Juan Batiz-Benet committed
8 9 10
)

/*
Juan Batiz-Benet's avatar
Juan Batiz-Benet committed
11
Datastore represents storage for any key-value pair.
Juan Batiz-Benet's avatar
Juan Batiz-Benet committed
12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33

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 Datastore interface {
Juan Batiz-Benet's avatar
go fmt  
Juan Batiz-Benet committed
34 35 36 37 38 39 40 41 42
	// 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.
43
	Put(key Key, value []byte) error
Juan Batiz-Benet's avatar
Juan Batiz-Benet committed
44

Juan Batiz-Benet's avatar
go fmt  
Juan Batiz-Benet committed
45 46
	// Get retrieves the object `value` named by `key`.
	// Get will return ErrNotFound if the key is not mapped to a value.
47
	Get(key Key) (value []byte, err error)
Juan Batiz-Benet's avatar
Juan Batiz-Benet committed
48

Juan Batiz-Benet's avatar
go fmt  
Juan Batiz-Benet committed
49 50 51 52 53
	// 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)
Juan Batiz-Benet's avatar
Juan Batiz-Benet committed
54

Juan Batiz-Benet's avatar
go fmt  
Juan Batiz-Benet committed
55
	// Delete removes the value for given `key`.
56
	Delete(key Key) error
Jeromy's avatar
Jeromy committed
57

58 59 60 61 62 63
	// 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
Vasily Kolobkov's avatar
Vasily Kolobkov committed
64
	//   for entry := range result.Next() { ... }
65
	//
Vasily Kolobkov's avatar
Vasily Kolobkov committed
66 67 68
	//   // or wait for the query to be completely done
	//   entries, _ := result.Rest()
	//   for entry := range entries { ... }
69
	//
70
	Query(q query.Query) (query.Results, error)
Jeromy's avatar
Jeromy committed
71 72
}

Jeromy's avatar
Jeromy committed
73
type Batching interface {
Jeromy's avatar
Jeromy committed
74
	Datastore
Jeromy's avatar
Jeromy committed
75

Jeromy's avatar
Jeromy committed
76
	Batch() (Batch, error)
Juan Batiz-Benet's avatar
Juan Batiz-Benet committed
77 78
}

Jeromy's avatar
Jeromy committed
79 80
var ErrBatchUnsupported = errors.New("this datastore does not support batching")

Juan Batiz-Benet's avatar
linting  
Juan Batiz-Benet committed
81 82
// ThreadSafeDatastore is an interface that all threadsafe datastore should
// implement to leverage type safety checks.
83 84
type ThreadSafeDatastore interface {
	Datastore
85

86 87 88
	IsThreadSafe()
}

89 90 91 92 93 94 95 96
// CheckedDatastore is an interface that should be implemented by datastores
// which may need checking on-disk data integrity.
type CheckedDatastore interface {
	Datastore

	Check() error
}

Łukasz Magiera's avatar
Łukasz Magiera committed
97 98
// CheckedDatastore is an interface that should be implemented by datastores
// which want to provide a mechanism to check data integrity and/or
99
// error correction.
Łukasz Magiera's avatar
Łukasz Magiera committed
100 101 102 103 104 105
type ScrubbedDatastore interface {
	Datastore

	Scrub() error
}

106
// GCDatastore is an interface that should be implemented by datastores which
107
// don't free disk space by just removing data from them.
108 109 110 111 112 113
type GCDatastore interface {
	Datastore

	CollectGarbage() error
}

114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133
// PersistentDatastore is an interface that should be implemented by datastores
// which can report disk usage.
type PersistentDatastore interface {
	Datastore

	// DiskUsage returns the space used by a datastore, in bytes.
	DiskUsage() (uint64, error)
}

// DiskUsage checks if a Datastore is a
// PersistentDatastore and returns its DiskUsage(),
// otherwise returns 0.
func DiskUsage(d Datastore) (uint64, error) {
	persDs, ok := d.(PersistentDatastore)
	if !ok {
		return 0, nil
	}
	return persDs.DiskUsage()
}

134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158
// TTLDatastore is an interface that should be implemented by datastores that
// support expiring entries.
type TTLDatastore interface {
	Datastore

	PutWithTTL(key Key, value interface{}, ttl time.Duration) error
	SetTTL(key Key, ttl time.Duration) error
}

// Txn is an interface for transactions that can be committed or rolled back.
type Txn interface {
	Datastore

	Commit() error
	Rollback()
}

// TxDatastore is an interface that should be implemented by datastores that
// support transactions.
type TxDatastore interface {
	Datastore

	NewTransaction() Txn
}

Juan Batiz-Benet's avatar
Juan Batiz-Benet committed
159
// Errors
Juan Batiz-Benet's avatar
Juan Batiz-Benet committed
160 161 162

// ErrNotFound is returned by Get, Has, and Delete when a datastore does not
// map the given key to a value.
Juan Batiz-Benet's avatar
Juan Batiz-Benet committed
163
var ErrNotFound = errors.New("datastore: key not found")
Juan Batiz-Benet's avatar
Juan Batiz-Benet committed
164 165 166 167

// 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.
Juan Batiz-Benet's avatar
Juan Batiz-Benet committed
168
var ErrInvalidType = errors.New("datastore: invalid type error")
Juan Batiz-Benet's avatar
Juan Batiz-Benet committed
169

Juan Batiz-Benet's avatar
Juan Batiz-Benet committed
170 171 172 173 174 175 176
// 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 GetBackedHas(ds Datastore, key Key) (bool, error) {
Juan Batiz-Benet's avatar
go fmt  
Juan Batiz-Benet committed
177 178 179 180 181 182 183 184 185
	_, err := ds.Get(key)
	switch err {
	case nil:
		return true, nil
	case ErrNotFound:
		return false, nil
	default:
		return false, err
	}
Juan Batiz-Benet's avatar
Juan Batiz-Benet committed
186
}
Jeromy's avatar
Jeromy committed
187

Jeromy's avatar
Jeromy committed
188
type Batch interface {
189
	Put(key Key, val []byte) error
Jeromy's avatar
Jeromy committed
190 191 192 193 194

	Delete(key Key) error

	Commit() error
}