buntdb

package
v0.0.0-...-a8cc34e Latest Latest
Warning

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

 Go to latest Published: Feb 12, 2020 License: LGPL-3.0, LGPL-3.0 Imports: 14 Imported by: 0

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

View Source 
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.
	// Slow. Very safe.
	Always = 2
)

Variables

View Source 
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")

	// ErrPersistenceActive is returned when post-loading data from an database
	// not opened with Open(":memory:").
	ErrPersistenceActive = errors.New("persistence active")

	// 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 string) bool) func(a, b string) bool

Desc is a helper function that changes the order of an index.

func IndexBinary 

func IndexBinary(a, b string) bool

IndexBinary is a helper function that returns true if 'a' is less than 'b'. This compares the raw binary of the string.

func IndexFloat 

func IndexFloat(a, b string) bool

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 IndexInt 

func IndexInt(a, b string) bool

IndexInt is a helper function that returns true if 'a' is less than 'b'.

func IndexJSON 

func IndexJSON(path string) func(a, b string) bool

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 

func IndexJSONCaseSensitive(path string) func(a, b string) bool

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 

func IndexRect(a string) (min, max []float64)

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 

func IndexString(a, b string) bool

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 

func IndexUint(a, b string) bool

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.

func Match 

func Match(key, pattern string) bool

Match returns true if the specified key matches the pattern. This is a very simple pattern matcher where '*' matches on any number characters and '?' matches on any one character.

func Point 

func Point(coords ...float64) string

Point is a helper function that converts a series of float64s to a rectangle for a spatial index.

func Rect 

func Rect(min, max []float64) string

Rect is helper function that returns a string representation of a rect. IndexRect() is the reverse function and can be used to generate a rect from a string.

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

	// OnExpired is used to custom handle the deletion option when a key
	// has been expired.
	OnExpired func(keys []string)

	// OnExpiredSync will be called inside the same transaction that is performing
	// the deletion of expired items. If OnExpired is present then this callback
	// will not be called. If this callback is present, then the deletion of the
	// timeed-out item is the explicit responsibility of this callback.
	OnExpiredSync func(key, value string, tx *Tx) error
}

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 

func Open(path string) (*DB, error)

Open opens a database at the provided path. If the file does not exist then it will be created automatically.

func (*DB) Backup 

func (db *DB) Backup(dst string) error

Backup will copy the database file. This operation does not block the database.

func (*DB) Begin 

func (db *DB) Begin(writable bool) (*Tx, error)

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 

func (db *DB) Close() error

Close releases all database resources. All transactions must be closed before closing the database.

func (*DB) CreateIndex deprecated 

func (db *DB) CreateIndex(name, pattern string,
	less ...func(a, b 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.

Deprecated: Use Transactions

func (*DB) CreateSpatialIndex deprecated 

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.

Deprecated: Use Transactions

func (*DB) DropIndex deprecated 

func (db *DB) DropIndex(name string) error

DropIndex removes an index.

Deprecated: Use Transactions

func (*DB) Indexes deprecated 

func (db *DB) Indexes() ([]string, error)

Indexes returns a list of index names.

Deprecated: Use Transactions

func (*DB) ReadConfig 

func (db *DB) ReadConfig(config *Config) error

ReadConfig returns the database configuration.

func (*DB) ReplaceIndex deprecated 

func (db *DB) ReplaceIndex(name, pattern string,
	less ...func(a, b string) bool) error

ReplaceIndex 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. If a previous index with the same name exists, that index will be deleted.

Deprecated: Use Transactions

func (*DB) ReplaceSpatialIndex deprecated 

func (db *DB) ReplaceSpatialIndex(name, pattern string,
	rect func(item string) (min, max []float64)) error

ReplaceSpatialIndex 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. If a previous index with the same name exists, that index will be deleted.

Deprecated: Use Transactions

func (*DB) SetConfig 

func (db *DB) SetConfig(config Config) error

SetConfig updates the database configuration.

func (*DB) Shrink 

func (db *DB) Shrink() error

Shrink will make the database file smaller by removing redundant log entries. This operation does not block the database.

func (*DB) Update 

func (db *DB) Update(fn func(tx *Tx) error) error

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.

func (*DB) View 

func (db *DB) View(fn func(tx *Tx) error) error

View executes a function within a managed read-only transaction. When a non-nil error is returned from the function that error will be return to the caller of View().

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 SyncPolicy 

type SyncPolicy int

SyncPolicy represents how often data is synced to disk.

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 

func (tx *Tx) Ascend(index string,
	iterator func(key, value string) bool) error

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) AscendEqual 

func (tx *Tx) AscendEqual(index, pivot string,
	iterator func(key, value string) bool) error

AscendEqual calls the iterator for every item in the database that equals 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) AscendGreaterOrEqual 

func (tx *Tx) AscendGreaterOrEqual(index, pivot string,
	iterator func(key, value string) 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) AscendKeys 

func (tx *Tx) AscendKeys(pattern string,
	iterator func(key, value string) bool) error

AscendKeys allows for iterating through keys based on the specified pattern.

func (*Tx) AscendLessThan 

func (tx *Tx) AscendLessThan(index, pivot string,
	iterator func(key, value string) 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, greaterOrEqual, lessThan string,
	iterator func(key, value string) 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 

func (tx *Tx) Commit() error

Commit writes all changes to disk. 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, pattern string,
	less ...func(a, b 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, pattern string,
	opts *IndexOptions,
	less ...func(a, b string) bool) error

CreateIndexOptions is the same as CreateIndex except that it allows for additional options.

func (*Tx) CreateSpatialIndex 

func (tx *Tx) 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 (*Tx) CreateSpatialIndexOptions 

func (tx *Tx) CreateSpatialIndexOptions(name, pattern string,
	opts *IndexOptions,
	rect func(item string) (min, max []float64)) error

CreateSpatialIndexOptions is the same as CreateSpatialIndex except that it allows for additional options.

func (*Tx) Delete 

func (tx *Tx) Delete(key string) (val string, err error)

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) DeleteAll 

func (tx *Tx) DeleteAll() error

DeleteAll deletes all items from the database.

func (*Tx) Descend 

func (tx *Tx) Descend(index string,
	iterator func(key, value string) bool) error

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) DescendEqual 

func (tx *Tx) DescendEqual(index, pivot string,
	iterator func(key, value string) bool) error

DescendEqual calls the iterator for every item in the database that equals 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) DescendGreaterThan 

func (tx *Tx) DescendGreaterThan(index, pivot string,
	iterator func(key, value string) 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) DescendKeys 

func (tx *Tx) DescendKeys(pattern string,
	iterator func(key, value string) bool) error

DescendKeys allows for iterating through keys based on the specified pattern.

func (*Tx) DescendLessOrEqual 

func (tx *Tx) DescendLessOrEqual(index, pivot string,
	iterator func(key, value string) 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, lessOrEqual, greaterThan string,
	iterator func(key, value string) 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) DropIndex 

func (tx *Tx) DropIndex(name string) error

DropIndex removes an index.

func (*Tx) Get 

func (tx *Tx) Get(key string, ignoreExpired ...bool) (val string, err error)

Get returns a value for a key. If the item does not exist or if the item has expired then ErrNotFound is returned. If ignoreExpired is true, then the found value will be returned even if it is expired.

func (*Tx) GetLess 

func (tx *Tx) GetLess(index string) (func(a, b string) bool, error)

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) GetRect 

func (tx *Tx) GetRect(index string) (func(s string) (min, max []float64),
	error)

GetRect returns the rect function for an index. This is handy for doing ad-hoc searches inside a transaction. Returns ErrNotFound if the index is not found or there is no rect function bound to the index

func (*Tx) Indexes 

func (tx *Tx) Indexes() ([]string, error)

Indexes returns a list of index names.

func (*Tx) Intersects 

func (tx *Tx) Intersects(index, bounds string,
	iterator func(key, value string) bool) error

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) Len 

func (tx *Tx) Len() (int, error)

Len returns the number of items in the database

func (*Tx) Nearby 

func (tx *Tx) Nearby(index, bounds string,
	iterator func(key, value string, dist float64) bool) error

Nearby searches for rectangle items that are nearby a target rect. All items belonging to the specified index will be returned in order of nearest to farthest. 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. The dist param is the distance of the bounding boxes. In the case of simple 2D points, it's the distance of the two 2D points squared.

func (*Tx) Rollback 

func (tx *Tx) Rollback() error

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, 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.

Only a writable transaction can be used with this operation. This operation is not allowed during iterations such as Ascend* & Descend*.

func (*Tx) TTL 

func (tx *Tx) TTL(key string) (time.Duration, error)

TTL returns the remaining time-to-live for an item. A negative duration will be returned for items that do not have an expiration.

Source Files

View all Source files

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.