badger-store.md

BadgerStore

• Overview
• Implementation
  • In-Memory and Persistent
  • Store methods
  • Lifecycle Methods
  • Data Methods
    • Backups
    • Restorations
  • Accessor Methods
    • Prefixed and Sorted Get All
    • Clear All Key-Value Pairs
    • Len

Overview

The bagder submodule provides a BadgerStore interface that can be used with the SM(S)T as both an in-memory and persistent DB backend for the trie. It also exposes numerous methods not needed by the SM(S)T for use as a general purpose key-value store.

NOTE: The MapStore interface used by the SM(S)T is implemented by the badger BadgerStore interface and can be used as the database for the trie. It's interface also has other features making it useful for uses outside of the SM(S)T itself.

Implementation

The BadgerStore is implemented in kvstore.go and is a wrapper around the BadgerDB v4 key-value database.

The interface defines simple key-value store accessor methods as well as other methods desired from a key-value database in general, this can be found in kvstore.go.

In-Memory and Persistent

The BadgerStore implementation can be used as an in-memory or persistent key-value store. The NewBadgerStore function takes a path argument that can be used to specify a path to a directory to store the database files. If the path is an empty string, the database will be stored in-memory.

NOTE: When providing a path for a persistent database, the directory must exist and be writeable by the user running the application.

Store methods

As a key-value store the BadgerStore interface defines the simple Get, Set and Delete methods to access and modify the underlying database.

Lifecycle Methods

The Stop method must be called when the BadgerStore is no longer needed. This method closes the underlying database and frees up any resources used by the BadgerStore.

For persistent databases, the Stop method should be called when the application no longer needs to access the database. For in-memory databases, the Stop method should be called when the BadgerStore is no longer needed.

NOTE: A persistent BadgerStore that is not stopped will stop another BadgerStore from opening the database.

Data Methods

The BadgerStore interface provides two methods to allow backups and restorations.

Backups

The Backup method takes an io.Writer and a bool to indicate whether the backup should be incremental or not. The io.Writer is then filled with the contents of the database in an opaque format used by the underlying database for this purpose.

When the incremental bool is false a full backup will be performed, otherwise an incremental backup will be performed. This is enabled by the BadgerStore keeping the timestamp of its last backup and only backing up data that has been modified since the last backup.

Restorations

The Restore method takes an io.Reader and restores the database from this reader.

The BadgerStore calling the Restore method is expected to be initialised and open, otherwise the restore will fail.

NOTE: Any data contained in the BadgerStore when calling restore will be overwritten.

Accessor Methods

The accessor methods enable simpler access to the underlying database for certain tasks that are desirable in a key-value store.

Prefixed and Sorted Get All

The GetAll method supports the retrieval of all keys and values, where the key has a specific prefix. The descending bool indicates whether the keys should be returned in descending order or not.

NOTE: In order to retrieve all keys and values the empty prefix []byte{} or nil should be used to match all keys

Clear All Key-Value Pairs

The ClearAll method removes all key-value pairs from the database.

NOTE: The ClearAll method is intended to debug purposes and should not be used in production unless necessary

Len

The Len method returns the number of keys in the database, similarly to how the len function can return the length of a map.