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 ¶
- Constants
- Variables
- func IndexBinary(a, b string) bool
- func IndexFloat(a, b string) bool
- func IndexInt(a, b string) bool
- func IndexJSON(path string) func(a, b string) bool
- func IndexJSONCaseSensitive(path string) func(a, b string) bool
- func IndexRect(a string) (min, max []float64)
- func IndexString(a, b string) bool
- func IndexUint(a, b string) bool
- func Point(coords ...float64) string
- func Rect(min, max []float64) string
- type Config
- type DB
- func (db *DB) Close() error
- func (db *DB) CreateIndex(name, pattern string, less func(a, b string) bool) error
- func (db *DB) CreateSpatialIndex(name, pattern string, rect func(item string) (min, max []float64)) error
- func (db *DB) DropIndex(name string) error
- func (db *DB) Indexes() ([]string, error)
- func (db *DB) ReadConfig(config *Config) error
- func (db *DB) SetConfig(config Config) error
- func (db *DB) Shrink() error
- func (db *DB) Update(fn func(tx *Tx) error) error
- func (db *DB) View(fn func(tx *Tx) error) error
- type Iterator
- type SetOptions
- type SyncPolicy
- type Tx
- func (tx *Tx) Ascend(index string, iterator Iterator) error
- func (tx *Tx) AscendGreaterOrEqual(index, pivot string, iterator Iterator) error
- func (tx *Tx) AscendLessThan(index, pivot string, iterator Iterator) error
- func (tx *Tx) AscendRange(index, greaterOrEqual, lessThan string, iterator Iterator) error
- func (tx *Tx) Delete(key string) (val string, err error)
- func (tx *Tx) Descend(index string, iterator Iterator) error
- func (tx *Tx) DescendGreaterThan(index, pivot string, iterator Iterator) error
- func (tx *Tx) DescendLessOrEqual(index, pivot string, iterator Iterator) error
- func (tx *Tx) DescendRange(index, lessOrEqual, greaterThan string, iterator Iterator) error
- func (tx *Tx) Get(key string) (val string, err error)
- func (tx *Tx) Intersects(index, bounds string, iterator Iterator) error
- func (tx *Tx) Len() (int, error)
- func (tx *Tx) Set(key, value string, opts *SetOptions) (previousValue string, replaced bool, err error)
- func (tx *Tx) TTL(key string) (time.Duration, error)
Constants ¶
const ( // Never is used to disable syncing data to disk. // The faster and less safe method. Never SyncPolicy = 0 // EverySecond is used to sync data to disk every second. // It's pretty fast and you can lose 1 second of data if there // is a disaster. // This is the recommended setting. EverySecond = 1 // Always is used to sync data after every write to disk. // Very very slow. Very safe. Always = 2 )
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") // ErrInvalidSyncPolicy is returned for an invalid SyncPolicy value. ErrInvalidSyncPolicy = errors.New("invalid sync policy") // ErrShrinkInProcess is returned when a shrink operation is in-process. ErrShrinkInProcess = errors.New("shrink is in-process") )
Functions ¶
func IndexBinary ¶
IndexBinary is a helper function that returns true if 'a' is less than 'b'. This compares the raw binary of the string.
func IndexFloat ¶
IndexFloat 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 IndexJSON ¶
IndexJSON provides for the ability to create an index on any JSON field. When the field is a string, the comparison will be case-insensitive. It returns a helper function used by CreateIndex.
func IndexJSONCaseSensitive ¶
IndexJSONCaseSensitive provides for the ability to create an index on any JSON field. When the field is a string, the comparison will be case-sensitive. It returns a helper function used by CreateIndex.
func IndexRect ¶
IndexRect is a helper function that converts string to a rect. Rect() is the reverse function and can be used to generate a string from a rect.
func IndexString ¶
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 IndexUint ¶
IndexUint 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 { // SyncPolicy adjusts how often the data is synced to disk. // This value can be Never, EverySecond, or Always. // The default is EverySecond. SyncPolicy SyncPolicy // AutoShrinkPercentage is used by the background process to trigger // a shrink of the aof file when the size of the file is larger than the // percentage of the result of the previous shrunk file. // For example, if this value is 100, and the last shrink process // resulted in a 100mb file, then the new aof file must be 200mb before // a shrink is triggered. AutoShrinkPercentage int // AutoShrinkMinSize defines the minimum size of the aof file before // an automatic shrink can occur. AutoShrinkMinSize int // AutoShrinkDisabled turns off automatic background shrinking AutoShrinkDisabled bool }
Config represents database configuration options. These options are used to change various behaviors of the database.
type DB ¶
type DB struct {
// 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) Close ¶
Close releases all database resources. All transactions must be closed before closing the database.
func (*DB) CreateIndex ¶
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. 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 (*DB) CreateSpatialIndex ¶
func (db *DB) CreateSpatialIndex(name, pattern string, rect func(item string) (min, max []float64)) error
CreateSpatialIndex builds a new index and populates it with items. The items are organized in an r-tree and can be retrieved using the Intersects method. An error will occur if an index with the same name already exists.
The rect function converts a string to a rectangle. The rectangle is represented by two arrays, min and max. Both arrays may have a length between 1 and 20, and both arrays must match in length. A length of 1 is a one dimensional rectangle, and a length of 4 is a four dimension rectangle. There is support for up to 20 dimensions. The values of min must be less than the values of max at the same dimension. Thus min[0] must be less-than-or-equal-to max[0]. The IndexRect is a default function that can be used for the rect parameter.
func (*DB) ReadConfig ¶
ReadConfig returns the database configuration.
func (*DB) Shrink ¶
Shrink will make the database file smaller by removing redundant log entries. This operation does not block the database.
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 Iterator ¶
Iterator allows callers of Ascend* or Descend* to iterate in-order over portions of an index. When this function returns false, iteration will stop and the associated Ascend* or Descend* function will immediately return.
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 ¶
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 ¶
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 ¶
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) 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 writable transaction can be used for Delete() calls.
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 ¶
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 ¶
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 ¶
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) Intersects ¶
Intersects searches for rectangle items that intersect a target rect. The specified index must have been created by AddIndex() and the target is represented by the rect string. This string will be processed by the same bounds function that was passed to the CreateSpatialIndex() function. An invalid index will return an error.
func (*Tx) Set ¶
func (tx *Tx) Set(key, value string, opts *SetOptions) (previousValue string, 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.