1// Package db defines the database and transaction interfaces used by arbo.
 2package db
 3
 4import (
 5	"fmt"
 6	"io"
 7)
 8
 9// TypePebble defines the type of db that uses PebbleDB
10const (
11	TypePebble  = "pebble"
12	TypeLevelDB = "leveldb"
13)
14
15// ErrKeyNotFound is used to indicate that a key does not exist in the db.
16var ErrKeyNotFound = fmt.Errorf("key not found")
17
18// ErrTxnTooBig is used to indicate that a WriteTx is too big and can't include
19// more writes.
20var ErrTxnTooBig = fmt.Errorf("txn too big")
21
22// ErrConflict is returned when a transaction conflicts with another transaction. This can
23// happen if the read rows had been updated concurrently by another transaction.
24var ErrConflict = fmt.Errorf("txn conflict")
25
26// Options defines generic parameters for creating a new Database.
27type Options struct {
28	Path string
29}
30
31// Database wraps all database operations. All methods are safe for concurrent
32// use.
33type Database interface {
34	io.Closer
35
36	Reader
37
38	// WriteTx creates a new write transaction.
39	WriteTx() WriteTx
40
41	// Compact compacts the underlying storage.
42	Compact() error
43}
44
45// Reader contains the read-only database operations.
46type Reader interface {
47	// Get retrieves the value for the given key. If the key does not
48	// exist, returns the error ErrKeyNotFound
49	Get(key []byte) ([]byte, error)
50
51	// Iterate calls callback with all key-value pairs in the database whose key
52	// starts with prefix. The calls are ordered lexicographically by key.
53	//
54	// The iteration is stopped early when the callback function returns false.
55	//
56	// It is not safe to use the key or value slices after the callback returns.
57	// To use the values for longer, make a copy.
58	Iterate(prefix []byte, callback func(key, value []byte) bool) error
59}
60
61// WriteTx buffers database changes until they are committed or discarded.
62type WriteTx interface {
63	Reader
64
65	// Set adds a key-value pair. If the key already exists, its value is
66	// updated.
67	Set(key, value []byte) error
68	// Delete deletes a key and its value.
69	Delete(key []byte) error
70	// Apply applies the value-passed WriteTx into the given WriteTx,
71	// copying the key-values from the original WriteTx into the one from
72	// which the method is called.
73	// TODO Review once generics are ready: WriteTx is an interface, so
74	// Apply internally needs type assertions, revisit this once generics
75	// are ready.
76	Apply(WriteTx) error
77	// Commit commits the transaction into the db.
78	// Calling Commit more than once, or after Discard, is an error.
79	Commit() error
80	// Discard releases the transaction's resources as they don't need to be committed.
81	// This method can be safely called after any previous Commit or Discard call,
82	// for the sake of allowing deferred Discard calls.
83	Discard()
84}
85
86// UnwrapWriteTx unwraps (if possible) the WriteTx using Unwrap method
87func UnwrapWriteTx(tx WriteTx) WriteTx {
88	for {
89		wtx, ok := tx.(interface{ Unwrap() WriteTx })
90		if !ok {
91			return tx
92		}
93		tx = wtx.Unwrap()
94	}
95}