Skip to content
A key-value store with hash indexes
Go
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Enable Github Sponsors Oct 29, 2019
cmd Improve the stress app Mar 9, 2019
.gitignore Add indexing Dec 25, 2018
Gopkg.lock
Gopkg.toml Update logtic and bbolt Nov 8, 2019
LICENSE Initial commit Dec 18, 2018
README.md Update logtic and bbolt Nov 8, 2019
add.go Add rwlock to help with concurrency Jun 20, 2019
add_test.go
config.go Allow disabling sorting when migrating Jul 3, 2019
const.go Add indexing Dec 25, 2018
delete.go
delete_test.go Make tests faster Nov 8, 2019
ds.go Simplify Get methods, add options with new Max setting Dec 29, 2018
ds_test.go Update logtic and bbolt Nov 8, 2019
get.go Fix crash when trying to sort an unsorted table Sep 10, 2019
get_test.go Make tests faster Nov 8, 2019
gob.go Add indexing Dec 25, 2018
index.go
migrate.go Allow disabling sorting when migrating Jul 3, 2019
migrate_test.go Make tests faster Nov 8, 2019
options.go Static analysis fixes Mar 12, 2019
primary_key.go
register.go Add rwlock to help with concurrency Jun 20, 2019
register_test.go Numerous safety and test improvements May 21, 2019
table.go Add rwlock to help with concurrency Jun 20, 2019
update.go
update_test.go Fix issue when calling update with a new value on a sorted table Jul 3, 2019

README.md

DS

Go Report Card Godoc Releases LICENSE

Package ds (short for "data store") is a key-value store with hash indexes. It allows for rudementary but lightning fast retrevial of grouped or relevant data without having to iterate over all objects in the store.

Usage

Creating A Table

Properties of your table are defined using ds struct tags. There are three tags:

  • primary: The primary key for each row. Value must be unique and cannot be nil. There must be exactly 1 primary key.
  • index: A field where other rows that share the same value are grouped togther for quick retreival.
  • unique: A field where the value must be unique from all other rows.

Register your object

type exampleType struct {
    Primary string `ds:"primary"`
    Index   string `ds:"index"`
    Unique  string `ds:"unique"`
}

table, err := ds.Register(exampleType{}, "./data.db");
if err != nil {
    panic("Error registering table: %s", err.Error())
}

Add something

object := exampleType{
    Primary: "foo",
    Index: "bar",
    Unique: "baz"
}

err := table.Add(object);
if err != nil {
    panic("Error adding to table: %s", err.Error())
}

Get A Single Object

value, err := table.Get("foo")
if err != nil {
    panic("Error getting object: %s", err.Error())
}
if value == nil {
    // Nothing found with that primary key
}

// Now use your object
object := value.(exampleType)

Get Multiple Objects

The GetOptions struct defines optional parameters to a Get (that returns multiple entires). Pass nil for defaults.

values, err := table.GetIndex("Index", "bar", &ds.GetOptions{Sorted: true, Ascending: true})
if err != nil {
    panic("Error getting many objects: %s", err.Error())
}
if len(values) == 0 {
    // Nothing found with that index value
}

// Now use your objects
for _, v := range values {
    object := value.(exampleType)
}

Migrate a Table

As DS tables are tied to a specified struct, you may need to migrate a table to a newer struct. DS provides a built in method for migrating tables.

// Define a struct that maps to the current type used in the table
type oldType struct{}

// Define your new struct
type newType struct{}

result := ds.Migrate(ds.MigrateParams{
    TablePath: "/path/to/table.db",
    NewPath: "/path/to/table.db", // You can specify the same path, or a new one if you want
    OldType: oldType{},
    NewType: newType{},
    MigrateObject: func(o interface{}) (interface{}, error) {
        old := o.(oldType)
        // Here you can form the "new" entry based on
        // the old one.
        // Return the new entry.
        // Or, return an error
        // Or, return nothing and this entry will be skipped
        return newType{}, nil
    },
})
if !result.Success {
    // Migration failed.
    panic(result.Error)
}
You can’t perform that action at this time.