BadgerHold Documentation

BadgerHold is a high-level querying and indexing layer built on top of the Badger key-value database. It simplifies working with Go types by providing a way to store and find data using structured types rather than raw byte slices.

Key features include:

• Type Prefixing: Each Go type is automatically prefixed with its type name, allowing you to store multiple different types in a single Badger database without key collisions.
• Custom Serialization: By default, BadgerHold uses Gob encoding. You can optimize performance by implementing the GobEncoder/Decoder interfaces or provide custom encode/decode functions via the Options struct during Open.

Indexes in BadgerHold allow you to skip scanning records that do not meet specific criteria, significantly improving query performance for read-heavy datasets.

How they work:

• Indexes are stored in a reserved bucket named _indexes.
• They map index values back to the primary keys of the records they belong to.
• Trade-off: While indexes speed up reads, they increase disk I/O because every write operation must also update the relevant indexes.

You can define indexes using struct tags or by implementing the Storer interface for manual control.

BadgerHold is a high-level wrapper for BadgerDB that allows you to work directly with Go types, eliminating the need for manual data filtering code or an ORM layer.

Use BadgerHold when:

• You want to use BadgerDB but want to avoid manual serialization/deserialization.
• You want a simpler alternative to SQLite for Go-centric applications. Unlike SQLite, which requires schema migrations and table creation scripts, BadgerHold allows you to simply open a file and start inserting Go structs immediately without explicit database initialization or schema definitions.

BadgerHold compares types using standard Go rules (types must match exactly, e.g., int vs int32 will fail). For standard library types like time.Time, big.Int, etc., comparison works out of the box.

To support custom comparison for your own types, implement the Comparer interface by adding a Compare method:

Compare(other interface{}) (int, error)

If a type does not implement Comparer, BadgerHold falls back to comparing the string representation of the value lexicographically.

To use BadgerHold, you must configure badgerhold.Options and call badgerhold.Open. You should always defer store.Close() to ensure the underlying BadgerDB instance is shut down correctly.

Key configuration options:

• Dir: The directory where the database files will be stored.
• ValueDir: The directory where the actual values (data) will be stored.

options := badgerhold.DefaultOptions
options.Dir = "data"
options.ValueDir = "data"

store, err := badgerhold.Open(options)
defer store.Close()
if err != nil {
	// handle error
	log.Fatal(err)
}

When a struct field is a slice, you can use Contains, ContainsAll, or ContainsAny to check for membership.

Important: The In operator requirement The In operator (and ContainsAll/ContainsAny) expects a slice of interface{} ([]interface{}). You cannot pass a typed slice (like []string) directly into these methods due to Go's type system. Use the badgerhold.Slice() helper to convert your typed slice into the required []interface{} format.

// Querying a slice field
// If Set is []string{"1", "2", "3"}
// bh.Where("Set").Contains("1") is true

// Using the In operator with a typed slice
t := []string{"1", "2", "3", "4"}
// This works by converting the slice to []interface{}
where := badgerhold.Where("Id").In(badgerhold.Slice(t)...)

To create an index on a specific field in your Go struct, use the badgerhold:"index" struct tag. If you want to specify a custom name for the index, use the badgerholdIndex tag instead.

// Standard index using the default tag
type Person struct {
	Name     string
	Division string `badgerhold:"index"` // Creates an index for Division
}

// Custom index name
type Person struct {
	Name     string
	Division string `badgerholdIndex:"IdxDivision"` // Creates an index named IdxDivision
}

type Person struct {
	Name string
	Division string `badgerhold:"index"` // Creates an index for Division
}

// alternate struct tag if you wish to specify the index name
type Person struct {
	Name string
	Division string `badgerholdIndex:"IdxDivision"` // Creates an index named IdxDivision
}

By default, BadgerHold uses reflection to determine type names and indexes. To avoid the performance overhead of reflection, implement the Storer interface on your data types. This allows you to explicitly define the index prefix and the available indexes.

type MyType struct {
	ID string
}

// Implement Storer to skip reflection
func (m MyType) Type() string {
	return "MyType"
}

func (m MyType) Indexes() map[string]badgerhold.Index {
	return map[string]badgerhold.Index{
		"ID": {IndexFunc: func(name string, value interface{}) ([]byte, error) {
			// Custom index logic
			return nil, nil
		}},
	}
}

You can ensure a field contains unique values across all records of a specific type by using the badgerhold:"unique" struct tag.

If an Insert, Update, or Upsert operation attempts to violate this constraint, the operation will fail and return badgerhold.ErrUniqueExists.

type User struct {
  Name string
  Email string `badgerhold:"unique"` // Only one User can have this Email
}

BadgerHold uses a chained API to build queries. You start a query using badgerhold.Where("FieldName") and then chain operators to define criteria. To add more conditions to the same field, use .And("AnotherField"). You can also use .Or(otherQuery) to union results from a separate query.

Important: Field names passed to Where or And must start with an upper-case letter (e.g., "Name", not "name") because BadgerHold relies on exported fields for encoding. Using a lower-case field name will cause a panic.

s.Find(badgerhold.Where("FieldName").Eq(value).And("AnotherField").Lt(AnotherValue).Or(badgerhold.Where("FieldName").Eq(anotherValue)))