README
¶
RixxDB
RixxDB is a versioned, embedded, strongly-consistent, key-value database.
Features
- In-memory database
- Built-in encryption
- Built-in compression
- Built-in item versioning
- Multi-version concurrency control
- Rich transaction support with rollbacks
- Multiple concurrent readers without locking
- Atomicity, Consistency and Isolation from ACID
- Durable, configurable append-only file format for data persistence
- Flexible iteration of data; ascending, descending, ranges, and hierarchical ranges
Installation
go get github.com/abcum/rixxdb
Documentation
¶
Index ¶
- Constants
- Variables
- type Config
- type DB
- func (db *DB) Begin(writeable bool) (*TX, error)
- func (db *DB) Close() error
- func (db *DB) Flush() error
- func (db *DB) Load(r io.Reader) error
- func (db *DB) Save(w io.Writer) error
- func (db *DB) Shrink() error
- func (db *DB) Update(fn func(*TX) error) error
- func (db *DB) View(fn func(*TX) error) error
- type IT
- type KV
- type TX
- func (tx *TX) All(key []byte) (kvs []*KV, err error)
- func (tx *TX) AllL(key []byte, max uint64) (kvs []*KV, err error)
- func (tx *TX) AllP(key []byte, max uint64) (kvs []*KV, err error)
- func (tx *TX) AllR(beg, end []byte, max uint64) (kvs []*KV, err error)
- func (tx *TX) Cancel() error
- func (tx *TX) Closed() bool
- func (tx *TX) Clr(key []byte) (kv *KV, err error)
- func (tx *TX) ClrL(key []byte, max uint64) (kvs []*KV, err error)
- func (tx *TX) ClrP(key []byte, max uint64) (kvs []*KV, err error)
- func (tx *TX) ClrR(beg, end []byte, max uint64) (kvs []*KV, err error)
- func (tx *TX) Commit() error
- func (tx *TX) Cursor() *IT
- func (tx *TX) Del(ver uint64, key []byte) (kv *KV, err error)
- func (tx *TX) DelC(ver uint64, key, exp []byte) (kv *KV, err error)
- func (tx *TX) DelL(ver uint64, key []byte, max uint64) (kvs []*KV, err error)
- func (tx *TX) DelP(ver uint64, key []byte, max uint64) (kvs []*KV, err error)
- func (tx *TX) DelR(ver uint64, beg, end []byte, max uint64) (kvs []*KV, err error)
- func (tx *TX) Get(ver uint64, key []byte) (kv *KV, err error)
- func (tx *TX) GetL(ver uint64, key []byte, max uint64) (kvs []*KV, err error)
- func (tx *TX) GetP(ver uint64, key []byte, max uint64) (kvs []*KV, err error)
- func (tx *TX) GetR(ver uint64, beg, end []byte, max uint64) (kvs []*KV, err error)
- func (tx *TX) Put(ver uint64, key, val []byte) (kv *KV, err error)
- func (tx *TX) PutC(ver uint64, key, val, exp []byte) (kv *KV, err error)
- func (tx *TX) PutL(ver uint64, key, val []byte, max uint64) (kvs []*KV, err error)
- func (tx *TX) PutP(ver uint64, key, val []byte, max uint64) (kvs []*KV, err error)
- func (tx *TX) PutR(ver uint64, beg, end, val []byte, max uint64) (kvs []*KV, err error)
Constants ¶
const ( // FlushNever is used to prevent syncing of data to disk. When // this option is specified, all data changes are kept in memory, // and the database is run with no durability. FlushNever time.Duration = -1 // ShrinkNever is used to disable shrinking the data file. All // exact changes to the database are preserved with this option // but the data file can grow larger than the data stored. ShrinkNever time.Duration = -1 )
Variables ¶
var ( // ErrDbClosed occurs when a DB is accessed after it is closed. ErrDbClosed = errors.New("DB is not open") // ErrDbMemoryOnly occurs when persisting an in-memory DB. ErrDbMemoryOnly = errors.New("DB is memory-only") // ErrDbAlreadySyncing occurs when a sync is already in progress. ErrDbAlreadySyncing = errors.New("DB is already syncing") // ErrDbAlreadyShrinking occurs when a shrink is already in progress. ErrDbAlreadyShrinking = errors.New("DB is already shrinking") // ErrDbFileContentsInvalid occurs when the file is invalid or currupted. ErrDbFileContentsInvalid = errors.New("DB file contents invalid") // ErrDbInvalidEncryptionKey occurs when the provided encryption key is invalid. ErrDbInvalidEncryptionKey = errors.New("DB encryption key invalid") )
These errors can occur when opening or calling methods on a DB.
var ( // ErrTxClosed occurs when cancelling or committing a closed transaction. ErrTxClosed = errors.New("TX is closed") // ErrTxNotWritable occurs when writing or committing a read-only transaction. ErrTxNotWritable = errors.New("TX is not writable") // ErrTxNotEditable occurs when calling manually closing a managed transaction. ErrTxNotEditable = errors.New("TX is not editable") // ErrKvNotExpectedValue occurs when using a nil key in put, select, or delete methods. ErrTxKeyCanNotBeNil = errors.New("TX key can not be nil") // ErrKvNotExpectedValue occurs when conditionally putting or deleting a key-value item. ErrTxNotExpectedValue = errors.New("KV val is not expected value") )
These errors can occur when beginning or calling methods on a TX.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// SyncWrites specifies whether the file system should be forced to
// flush it's buffers to disk using 'fsync'. When the go programme
// exits, the operating system will eventually write the file changes
// to disk. Setting SyncWrites to 'true' will guarantee that data is
// flushed to persistent disk even if the system is powered down or
// the operating system crashes. This is only used when transactions
// are set to save to disk on commit by setting FlushPolicy to '0'.
SyncWrites bool
// FlushPolicy defines how often the data is synced to the append-only
// file on disk. '-1' ensures that the database is kept in-memory
// with no persistence, '0' ensures that the database is persisted
// to disk after every commit, and a number greater than 0 ensures
// that the database is committed to disk after the specified duration.
FlushPolicy time.Duration
// ShrinkPolicy defines how often the database append-only file is
// compacted, removing redundant log entries. '0' ensures that the
// database append-only file is never compacted, and a number greater
// than 0 ensures the database is compacted after the specified duration.
ShrinkPolicy time.Duration
// EncryptionKey enables the ability to specify an encryption key
// to be used when storing the input data in the underlying data tree.
// If the encryption key is specified, it must be either 16, 24, or
// 32 bytes in length in order to use AES-128, AES-192, or AES-256
// respectively. If no encryption key is specified then the data
// will not be encrypted before storage or when writing to disk.
EncryptionKey []byte
}
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 database which operates in memory, and persists to disk. A DB is safe to use from multiple goroutines concurrently. A DB can have only one read-write transaction open at a time, but allows an unlimited number of concurrent read-only transactions at a time, each with its own consistent view of the data as it existed when the transaction started.
func Open ¶
Open creates and opens a database at the given path. If the file does not exist then it will be created automatically. Passing in a nil Config will cause Rixx to use the default options.
func (*DB) Begin ¶
Begin starts a new transaction. Multiple read-only transactions can be used concurrently but only one write transaction can be used at a time. Starting multiple write transactions will cause the calls to be serialized until the current write transaction finishes.
func (*DB) Flush ¶
Flush ensures that all database operations are flushed to the underlying storage. If the database is currently performing a shrink from a previous call to this method, then the call will be ignored. This does nothing on in-memory databases.
func (*DB) Load ¶
Load loads database operations from a reader. This can be used to playback a database snapshot into an already running database.
func (*DB) Save ¶
Save saves all database operations to a writer. This can be used to save a database snapshot to a secondary file or stream.
func (*DB) Shrink ¶
Shrink ensures that all unnecessary database operations that have been flushed to disk are removed, reducing the output of the append-only log files. If the database is currently performing a shrink from a previous call to this method, then the call will be ignored. This only works for certain storage types, and does nothing on in-memory databases.
func (*DB) Update ¶
Update executes a function within the context of a read-write managed transaction. If no error is returned from the function then the transaction is committed. If an error is returned then the entire transaction is rolled back. Any error that is returned from the function or returned from the commit is returned from the Update() method. Attempting to manually commit or rollback within the function will cause a panic.
type KV ¶
type KV struct {
// contains filtered or unexported fields
}
KV represents a KV item stored in the database.
type TX ¶
type TX struct {
// contains filtered or unexported fields
}
TX represents a transaction for modifying the contents of the database. A TX is not safe to use from multiple goroutines concurrently. A TX emits the events `cancel` and `commit` when the transaction is cancelled and committed respectively.
func (*TX) AllR ¶
AllR retrieves the range of `max` rows between `beg` (inclusive) and `end` (exclusive). To return the range in descending order, ensure that `end` sorts lower than `beg` in the key value store.
func (*TX) ClrR ¶
ClrR removes the range of `max` rows between `beg` (inclusive) and `end` (exclusive). To return the range in descending order, ensure that `end` sorts lower than `beg` in the key value store.
func (*TX) DelC ¶
DelC conditionally deletes a key if the existing value is equal to the expected value.
func (*TX) DelR ¶
DelR deletes the range of `max` rows between `beg` (inclusive) and `end` (exclusive). To delete the range in descending order, ensure that `end` sorts lower than `beg` in the key value store.
func (*TX) GetR ¶
GetR retrieves the range of `max` rows between `beg` (inclusive) and `end` (exclusive). To return the range in descending order, ensure that `end` sorts lower than `beg` in the key value store.
func (*TX) PutC ¶
PutC conditionally sets the value for a key if the existing value is equal to the expected value. To conditionally set a value only if there is no existing entry pass nil for the expected value.
Source Files
Directories