store

README

Store

Package store provides a fast and efficient file-based key-value store.

Usage & Examples

Examples can be found on the documentation for the library

Documentation

Overview

Package store provides a fast and efficient file-based key-value store.

Index

• type Options
• type Store
  • func New(dataDir string, storeName string, options *Options) (*Store, error)
  • func (s *Store) BackupTo(filePath string) error
  • func (s *Store) Close()
  • func (s *Store) CopyTo(writer io.Writer) error
  • func (s *Store) Count() int
  • func (s *Store) Delete(key string) error
  • func (s *Store) ForEach(cb func(key string, idx int, value []byte) error) error
  • func (s *Store) Get(key string) []byte
  • func (s *Store) Truncate() error
  • func (s *Store) Write(key string, value []byte) error

Examples

• New
• Store.Count
• Store.Delete
• Store.ForEach
• Store.Get
• Store.Truncate
• Store.Write

Types

type Options

type Options struct {
	Mode       fs.FileMode // Defaults to 0644
	Extension  string      // Defaults to .db
	BucketName string      // Defaults to the store name
}

Options describes options for creating a new store

type Store

type Store struct {
	Name    string
	Options Options
	// contains filtered or unexported fields
}

Store describes a store object

func New

func New(dataDir string, storeName string, options *Options) (*Store, error)

New will create or open a store with the given store name at the specified data directory. Options may be nil and the defaults will be used.

Example

package main

import (
	"github.com/ecnepsnai/store"
)

func main() {
	store, err := store.New("/path/to/your/data/dir", "StoreName", &store.Options{
		Extension: ".dat",
		Mode:      0600,
	})
	if err != nil {
		panic(err)
	}

	// Don't forget to close your store when you're finished (such as when the application exits)
	store.Close()
}

func (*Store) BackupTo

func (s *Store) BackupTo(filePath string) error

BackupTo will make a copy of the store to the specified file path. The file will have the same mode as used when the store was created as specified in the options.

func (*Store) Close

func (s *Store) Close()

Close will close the store. This may block if there are any ongoing writes.

func (*Store) CopyTo

func (s *Store) CopyTo(writer io.Writer) error

CopyTo will make a copy of the store to the specified writer without blocking the store

func (*Store) Count

func (s *Store) Count() int

Count will return the number of objects in the store.

Example

package main

import (
	"fmt"
	"os"

	"github.com/ecnepsnai/store"
)

func main() {
	tmpDir, _ := os.MkdirTemp("", "store")
	defer os.RemoveAll(tmpDir)
	store, err := store.New(tmpDir, "ExampleCount", nil)
	if err != nil {
		panic(err)
	}
	defer store.Close()

	store.Write("key1", []byte("value1"))

	count := store.Count()
	fmt.Printf("Count: %d\n", count)
}

Output:

Count: 1

func (*Store) Delete

func (s *Store) Delete(key string) error

Delete will delete the object with the specified key from the store. If they key does not exist it does nothing.

Example

package main

import (
	"fmt"
	"os"

	"github.com/ecnepsnai/store"
)

func main() {
	tmpDir, _ := os.MkdirTemp("", "store")
	defer os.RemoveAll(tmpDir)
	store, err := store.New(tmpDir, "ExampleDelete", nil)
	if err != nil {
		panic(err)
	}
	defer store.Close()

	store.Write("key1", []byte("value1"))
	fmt.Printf("Value Before: %s\n", store.Get("key1"))

	store.Delete("key1")
	fmt.Printf("Value After: %s\n", store.Get("key1"))

}

Output:

Value Before: value1
Value After:

func (*Store) ForEach

func (s *Store) ForEach(cb func(key string, idx int, value []byte) error) error

ForEach will invoke cb for each object in the store with the key, index, and the value for that object

Example

package main

import (
	"fmt"
	"os"

	"github.com/ecnepsnai/store"
)

func main() {
	tmpDir, _ := os.MkdirTemp("", "store")
	defer os.RemoveAll(tmpDir)
	store, err := store.New(tmpDir, "ExampleForEach", nil)
	if err != nil {
		panic(err)
	}
	defer store.Close()

	store.Write("key1", []byte("value1"))
	store.Write("key2", []byte("value2"))
	store.Write("key3", []byte("value3"))

	store.ForEach(func(key string, idx int, value []byte) error {
		fmt.Printf("%s: %s\n", key, value)
		return nil
	})
}

Output:

key1: value1
key2: value2
key3: value3

func (*Store) Get

func (s *Store) Get(key string) []byte

Get will fetch the given key from the store and return its data, or nil if no record was found.

Example

package main

import (
	"fmt"
	"os"

	"github.com/ecnepsnai/store"
)

func main() {
	tmpDir, _ := os.MkdirTemp("", "store")
	defer os.RemoveAll(tmpDir)
	store, err := store.New(tmpDir, "ExampleGet", nil)
	if err != nil {
		panic(err)
	}
	defer store.Close()

	store.Write("key1", []byte("value1"))

	value := store.Get("key1")
	if value == nil {
		panic("No object with key")
	}

	fmt.Printf("Value: %s\n", value)
}

Output:

Value: value1

func (*Store) Truncate

func (s *Store) Truncate() error

Truncate will remove all keys from the store

Example

package main

import (
	"fmt"
	"os"

	"github.com/ecnepsnai/store"
)

func main() {
	tmpDir, _ := os.MkdirTemp("", "store")
	defer os.RemoveAll(tmpDir)
	store, err := store.New(tmpDir, "ExampleTruncate", nil)
	if err != nil {
		panic(err)
	}
	defer store.Close()

	store.Write("key1", []byte("value1"))
	fmt.Printf("Count Before: %d\n", store.Count())

	if err := store.Truncate(); err != nil {
		panic(err)
	}

	fmt.Printf("Count After: %d\n", store.Count())
}

Output:

Count Before: 1
Count After: 0

func (*Store) Write

func (s *Store) Write(key string, value []byte) error

Write saves a new object or updates an existing object in the store

Example

package main

import (
	"os"

	"github.com/ecnepsnai/store"
)

func main() {
	tmpDir, _ := os.MkdirTemp("", "store")
	defer os.RemoveAll(tmpDir)
	store, err := store.New(tmpDir, "ExampleWrite", nil)
	if err != nil {
		panic(err)
	}
	defer store.Close()

	store.Write("key1", []byte("value1"))
	store.Write("key2", []byte("value2"))
}