README
¶
Documentation
¶
Overview ¶
Package buntdb implements a low-level in-memory key/value store in pure Go. It persists to disk, is ACID compliant, and uses locking for multiple readers and a single writer. Bunt is ideal for projects that need a dependable database, and favor speed over data size.
Index ¶
- Variables
- func Desc(less func(a, b interface{}, fields []string) bool) func(a, b interface{}, fields []string) bool
- func IndexFloat64(ia, ib interface{}, fields []string) bool
- func IndexIString(ia, ib interface{}, fields []string) bool
- func IndexInt(ia, ib interface{}, fields []string) bool
- func IndexString(ia, ib interface{}, fields []string) bool
- func IndexUint64(ia, ib interface{}, fields []string) bool
- type Config
- type DB
- type IndexOptions
- type SetOptions
- type Tx
- func (tx *Tx) Ascend(index string, iterator func(value interface{}) bool) error
- func (tx *Tx) AscendGreaterOrEqual(index string, pivot interface{}, iterator func(value interface{}) bool) error
- func (tx *Tx) AscendLessThan(index string, pivot interface{}, iterator func(value interface{}) bool) error
- func (tx *Tx) AscendRange(index string, greaterOrEqual, lessThan interface{}, ...) error
- func (tx *Tx) Commit() error
- func (tx *Tx) CreateIndex(name string, fields []string, ...) error
- func (tx *Tx) CreateIndexOptions(name string, fields []string, opts *IndexOptions, ...) error
- func (tx *Tx) Delete(key string) (val interface{}, err error)
- func (tx *Tx) DeleteAll() error
- func (tx *Tx) Descend(index string, iterator func(value interface{}) bool) error
- func (tx *Tx) DescendGreaterThan(index string, pivot interface{}, iterator func(value interface{}) bool) error
- func (tx *Tx) DescendLessOrEqual(index string, pivot interface{}, iterator func(value interface{}) bool) error
- func (tx *Tx) DescendRange(index string, lessOrEqual, greaterThan interface{}, ...) error
- func (tx *Tx) DropIndex(name string) error
- func (tx *Tx) Get(key string) (val interface{}, err error)
- func (tx *Tx) GetLess(index string) (func(a, b interface{}, fields []string) bool, error)
- func (tx *Tx) Indexes() ([]string, error)
- func (tx *Tx) Len() (int, error)
- func (tx *Tx) Rollback() error
- func (tx *Tx) Set(key string, value interface{}, opts *SetOptions) (previousValue interface{}, replaced bool, err error)
- func (tx *Tx) TTL(key string) (time.Duration, error)
Constants ¶
This section is empty.
Variables ¶
var ( // ErrTxNotWritable is returned when performing a write operation on a // read-only transaction. ErrTxNotWritable = errors.New("tx not writable") // ErrTxClosed is returned when committing or rolling back a transaction // that has already been committed or rolled back. ErrTxClosed = errors.New("tx closed") // ErrNotFound is returned when an item or index is not in the database. ErrNotFound = errors.New("not found") // ErrInvalid is returned when the database file is an invalid format. ErrInvalid = errors.New("invalid database") // ErrDatabaseClosed is returned when the database is closed. ErrDatabaseClosed = errors.New("database closed") // ErrIndexExists is returned when an index already exists in the database. ErrIndexExists = errors.New("index exists") // ErrInvalidOperation is returned when an operation cannot be completed. ErrInvalidOperation = errors.New("invalid operation") // ErrTxIterating is returned when Set or Delete are called while iterating. ErrTxIterating = errors.New("tx is iterating") )
Functions ¶
func Desc ¶
func Desc(less func(a, b interface{}, fields []string) bool) func(a, b interface{}, fields []string) bool
Desc is a helper function that changes the order of an index.
func IndexFloat64 ¶
IndexFloat64 is a helper function that returns true if 'a' is less than 'b'. This compares float64s that are added to the database using the Float() conversion function.
func IndexIString ¶
IndexString is a helper function that return true if 'a' is less than 'b'. This is a case-insensitive comparison. Use the IndexBinary() for comparing case-sensitive strings.
func IndexString ¶
IndexInt is a helper function that returns true if 'a' is less than 'b'.
func IndexUint64 ¶
IndexUint64 is a helper function that returns true if 'a' is less than 'b'. This compares uint64s that are added to the database using the Uint() conversion function.
Types ¶
type Config ¶
type Config struct {
// OnExpired is used to custom handle the deletion option when a key
// has been expired.
OnExpired func(keys []string)
}
Config represents database configuration options. These options are used to change various behaviors of the database.
type DB ¶
type DB struct {
Name string // A given name, not used internally
// contains filtered or unexported fields
}
DB represents a collection of key-value pairs that persist on disk. Transactions are used for all forms of data access to the DB.
func Open ¶
Open opens a database at the provided path. If the file does not exist then it will be created automatically.
func (*DB) Begin ¶
Begin opens a new transaction. Multiple read-only transactions can be opened at the same time but there can only be one read/write transaction at a time. Attempting to open a read/write transactions while another one is in progress will result in blocking until the current read/write transaction is completed.
All transactions must be closed by calling Commit() or Rollback() when done.
func (*DB) Close ¶
Close releases all database resources. All transactions must be closed before closing the database.
func (*DB) ReadConfig ¶
ReadConfig returns the database configuration.
func (*DB) Update ¶
Update executes a function within a managed read/write transaction. The transaction has been committed when no error is returned. In the event that an error is returned, the transaction will be rolled back. When a non-nil error is returned from the function, the transaction will be rolled back and the that error will be return to the caller of Update().
Executing a manual commit or rollback from inside the function will result in a panic.
type IndexOptions ¶
type IndexOptions struct {
// CaseInsensitiveKeyMatching allow for case-insensitive
// matching on keys when setting key/values.
CaseInsensitiveKeyMatching bool
}
IndexOptions provides an index with additional features or alternate functionality.
type SetOptions ¶
type SetOptions struct {
// Expires indicates that the Set() key-value will expire
Expires bool
// TTL is how much time the key-value will exist in the database
// before being evicted. The Expires field must also be set to true.
// TTL stands for Time-To-Live.
TTL time.Duration
}
SetOptions represents options that may be included with the Set() command.
type Tx ¶
type Tx struct {
// contains filtered or unexported fields
}
Tx represents a transaction on the database. This transaction can either be read-only or read/write. Read-only transactions can be used for retrieving values for keys and iterating through keys and values. Read/write transactions can set and delete keys.
All transactions must be committed or rolled-back when done.
func (*Tx) Ascend ¶
Ascend calls the iterator for every item in the database within the range [first, last], until iterator returns false. When an index is provided, the results will be ordered by the item values as specified by the less() function of the defined index. When an index is not provided, the results will be ordered by the item key. An invalid index will return an error.
func (*Tx) AscendGreaterOrEqual ¶
func (tx *Tx) AscendGreaterOrEqual(index string, pivot interface{}, iterator func(value interface{}) bool) error
AscendGreaterOrEqual calls the iterator for every item in the database within the range [pivot, last], until iterator returns false. When an index is provided, the results will be ordered by the item values as specified by the less() function of the defined index. When an index is not provided, the results will be ordered by the item key. An invalid index will return an error.
func (*Tx) AscendLessThan ¶
func (tx *Tx) AscendLessThan(index string, pivot interface{}, iterator func(value interface{}) bool) error
AscendLessThan calls the iterator for every item in the database within the range [first, pivot), until iterator returns false. When an index is provided, the results will be ordered by the item values as specified by the less() function of the defined index. When an index is not provided, the results will be ordered by the item key. An invalid index will return an error.
func (*Tx) AscendRange ¶
func (tx *Tx) AscendRange(index string, greaterOrEqual, lessThan interface{}, iterator func(value interface{}) bool) error
AscendRange calls the iterator for every item in the database within the range [greaterOrEqual, lessThan), until iterator returns false. When an index is provided, the results will be ordered by the item values as specified by the less() function of the defined index. When an index is not provided, the results will be ordered by the item key. An invalid index will return an error.
func (*Tx) Commit ¶
An error is returned when a write error occurs, or when a Commit() is called from a read-only transaction.
func (*Tx) CreateIndex ¶
func (tx *Tx) CreateIndex(name string, fields []string, lessers ...func(a, b interface{}, fields []string) bool) error
CreateIndex builds a new index and populates it with items. The items are ordered in an b-tree and can be retrieved using the Ascend* and Descend* methods. An error will occur if an index with the same name already exists.
When a pattern is provided, the index will be populated with keys that match the specified pattern. This is a very simple pattern match where '*' matches on any number characters and '?' matches on any one character. The less function compares if string 'a' is less than string 'b'. It allows for indexes to create custom ordering. It's possible that the strings may be textual or binary. It's up to the provided less function to handle the content format and comparison. There are some default less function that can be used such as IndexString, IndexBinary, etc.
func (*Tx) CreateIndexOptions ¶
func (tx *Tx) CreateIndexOptions(name string, fields []string, opts *IndexOptions, lessers []func(a, b interface{}, fields []string) bool) error
CreateIndexOptions is the same as CreateIndex except that it allows for additional options.
func (*Tx) Delete ¶
Delete removes an item from the database based on the item's key. If the item does not exist or if the item has expired then ErrNotFound is returned.
Only a writable transaction can be used for this operation. This operation is not allowed during iterations such as Ascend* & Descend*.
func (*Tx) Descend ¶
Descend calls the iterator for every item in the database within the range [last, first], until iterator returns false. When an index is provided, the results will be ordered by the item values as specified by the less() function of the defined index. When an index is not provided, the results will be ordered by the item key. An invalid index will return an error.
func (*Tx) DescendGreaterThan ¶
func (tx *Tx) DescendGreaterThan(index string, pivot interface{}, iterator func(value interface{}) bool) error
DescendGreaterThan calls the iterator for every item in the database within the range [last, pivot), until iterator returns false. When an index is provided, the results will be ordered by the item values as specified by the less() function of the defined index. When an index is not provided, the results will be ordered by the item key. An invalid index will return an error.
func (*Tx) DescendLessOrEqual ¶
func (tx *Tx) DescendLessOrEqual(index string, pivot interface{}, iterator func(value interface{}) bool) error
DescendLessOrEqual calls the iterator for every item in the database within the range [pivot, first], until iterator returns false. When an index is provided, the results will be ordered by the item values as specified by the less() function of the defined index. When an index is not provided, the results will be ordered by the item key. An invalid index will return an error.
func (*Tx) DescendRange ¶
func (tx *Tx) DescendRange(index string, lessOrEqual, greaterThan interface{}, iterator func(value interface{}) bool) error
DescendRange calls the iterator for every item in the database within the range [lessOrEqual, greaterThan), until iterator returns false. When an index is provided, the results will be ordered by the item values as specified by the less() function of the defined index. When an index is not provided, the results will be ordered by the item key. An invalid index will return an error.
func (*Tx) Get ¶
Get returns a value for a key. If the item does not exist or if the item has expired then ErrNotFound is returned.
func (*Tx) GetLess ¶
GetLess returns the less function for an index. This is handy for doing ad-hoc compares inside a transaction. Returns ErrNotFound if the index is not found or there is no less function bound to the index
func (*Tx) Rollback ¶
Rollback closes the transaction and reverts all mutable operations that were performed on the transaction such as Set() and Delete().
Read-only transactions can only be rolled back, not committed.
func (*Tx) Set ¶
func (tx *Tx) Set(key string, value interface{}, opts *SetOptions) (previousValue interface{}, replaced bool, err error)
Set inserts or replaces an item in the database based on the key. The opt params may be used for additional functionality such as forcing the item to be evicted at a specified time. When the return value for err is nil the operation succeeded. When the return value of replaced is true, then the operaton replaced an existing item whose value will be returned through the previousValue variable. The results of this operation will not be available to other transactions until the current transaction has successfully committed.
Only a writable transaction can be used with this operation. This operation is not allowed during iterations such as Ascend* & Descend*.
Source Files
Directories