epos

README

README for epos

Introduction

epos is a embeddable persistent object store, written in Go. It is meant to store, retrieve, query and delete Go objects to a local file store. In this respect, it is NoSQL database, but it only works on local files and is embeddable into existing Go programs, so it can be thought of as the SQLite of NoSQL databases.

Here is a very basic overview how to use epos:

// open/create database:
db, err := epos.OpenDatabase("foo.db", epos.STORAGE_AUTO) // also available: STORAGE_DISKV, STORAGE_LEVELDB
// insert item:
id, err = db.Coll("users").Insert(new_user)
// update item:
err = db.Coll("users").Update(id, updated_user)
// index fields:
err = db.Coll("users").AddIndex("login")
// query items:
result, err = db.Coll("users").Query(epos.Expression("(eq username foobar)"))
for result.Next(&id, &data) {
	// handle data
}

License

See file LICENSE for details.

API Documentation

You can find the latest API documentation here: http://godoc.org/github.com/akrennmair/epos

Author

Andreas Krennmair ak@synflood.at

Documentation

Overview

epos is a embeddable persistent object store, written in Go. It is meant to store, retrieve, query and delete Go objects to a local file store. In this respect, it is NoSQL database, but it only works on local files and is embeddable into existing Go programs, so it can be thought of as the SQLite of NoSQL databases.

Here is a very basic overview how to use epos:

// open/create database:
db, err := epos.OpenDatabase("foo.db", epos.STORAGE_AUTO) // also available: STORAGE_DISKV, STORAGE_LEVELDB
// insert item:
id, err = db.Coll("users").Insert(new_user)
// update item:
err = db.Coll("users").Update(id, updated_user)
// index fields:
err = db.Coll("users").AddIndex("login")
// query items:
result, err = db.Coll("users").Query(epos.Expression("(eq username foobar)"))
for result.Next(&id, &data) {
	// handle data
}

Index

• func RegisterStorageBackend(name string, factoryFunc func(path string) StorageBackend) error
• type And
• type Collection
  • func (c *Collection) AddIndex(field string) error
  • func (c *Collection) Delete(id Id) error
  • func (c *Collection) Insert(value interface{}) (Id, error)
  • func (c *Collection) Query(q Condition) (*Result, error)
  • func (c *Collection) QueryAll() (*Result, error)
  • func (c *Collection) QueryId(id Id) (*Result, error)
  • func (c *Collection) Reindex(field string) error
  • func (c *Collection) RemoveIndex(field string) error
  • func (c *Collection) Update(id Id, value interface{}) error
  • func (c *Collection) Vacuum() error
• type Condition
  • func Expression(s string) (Condition, error)
• type Database
  • func OpenDatabase(path string, typ StorageType) (*Database, error)
  • func (db *Database) Close() error
  • func (db *Database) Coll(name string) *Collection
  • func (db *Database) Collections() ([]string, error)
  • func (db *Database) Remove() error
  • func (db *Database) Vacuum() error
• type DiskvStorageBackend
  • func (s *DiskvStorageBackend) Erase(key string) error
  • func (s *DiskvStorageBackend) Keys() <-chan string
  • func (s *DiskvStorageBackend) Read(key string) ([]byte, error)
  • func (s *DiskvStorageBackend) Write(key string, value []byte) error
• type Equals
• type Id
• type LevelDBStorageBackend
  • func (s *LevelDBStorageBackend) Erase(key string) error
  • func (s *LevelDBStorageBackend) Keys() <-chan string
  • func (s *LevelDBStorageBackend) Read(key string) ([]byte, error)
  • func (s *LevelDBStorageBackend) Write(key string, value []byte) error
• type Or
• type Result
  • func (r *Result) Count() int
  • func (r *Result) First(id *Id, result interface{}) bool
  • func (r *Result) Next(id *Id, result interface{}) bool
• type StorageBackend
  • func NewDiskvStorageBackend(path string) StorageBackend
  • func NewLevelDBStorageBackend(path string) StorageBackend
• type StorageType

Functions

func RegisterStorageBackend

func RegisterStorageBackend(name string, factoryFunc func(path string) StorageBackend) error

RegisterStorageBackend registers a new custom storage backend under a new name. If the name is already used, an error is returned.

In order to create a new custom storage backend, the programmer must also provide a function that takes the path where the storage backend must write its data (as a single file or within a directory) and that returns an object that satisfies the interface StorageBackend

Types

type And

type And []Condition

type Collection

type Collection struct {
	// contains filtered or unexported fields
}

func (*Collection) AddIndex

func (c *Collection) AddIndex(field string) error

AddIndex creates an index for a field. Existing records will be indexed, and future insert and update operations will index that field, as well. If an index for that field already exists, the AddIndex() is a no-op.

A field describes a top-level element of a struct or a particular key of a map.

func (*Collection) Delete

func (c *Collection) Delete(id Id) error

Delete deletes an object, identified by its ID, from the collection.

func (*Collection) Insert

func (c *Collection) Insert(value interface{}) (Id, error)

Insert inserts an object into the collection. It returns the object's ID and, if the insert fails, a non-nil error describing the problem.

func (*Collection) Query

func (c *Collection) Query(q Condition) (*Result, error)

Query takes a query in the form of a (possibly nested) Condition, and returns a Result object.

func (*Collection) QueryAll

func (c *Collection) QueryAll() (*Result, error)

QueryAll returns a Result object that will deliver all objects in the object store in no particular order.

func (*Collection) QueryId

func (c *Collection) QueryId(id Id) (*Result, error)

QueryId returns a Result object that will exactly deliver the object with the requested ID.

func (*Collection) Reindex

func (c *Collection) Reindex(field string) error

Reindex deletes and recreates the index for a field.

func (*Collection) RemoveIndex

func (c *Collection) RemoveIndex(field string) error

RemoveIndex removes an existing index for a field. It returns a non-nil error if an error occurs.

func (*Collection) Update

func (c *Collection) Update(id Id, value interface{}) error

Update replaces an existing object with a new object. If an error occurs during that operation, it returns a non-nil error.

func (*Collection) Vacuum

func (c *Collection) Vacuum() error

Vacuum expunges old entries that refer to deleted objects from all indexes of a collection.

type Condition

type Condition interface {
	// contains filtered or unexported methods
}

func Expression

func Expression(s string) (Condition, error)

Expression converts a S-Expr-based query to a structure of Condition objects. The following symbols are available for queries:

(id 1)					query entry with ID 1
(eq field-name value)		query all entries where field-name equals value
(or expr...)              OR all query sub-expressions
(and expr...)             AND all query sub-expressions

type Database

type Database struct {
	// contains filtered or unexported fields
}

func OpenDatabase

func OpenDatabase(path string, typ StorageType) (*Database, error)

OpenDatabase opens and if necessary creates a database identified by the provided path. It returns a database object and a non-nil error if an error occured while opening or creating the database.

func (*Database) Close

func (db *Database) Close() error

Close closes the database and frees the memory associated with all collections.

func (*Database) Coll

func (db *Database) Coll(name string) *Collection

Coll returns the collection of the specified name. If the collection doesn't exist yet, it is opened and/or created on the fly.

func (*Database) Collections

func (db *Database) Collections() ([]string, error)

Collections returns a list of collection names that are currently in the database.

func (*Database) Remove

func (db *Database) Remove() error

Remove physically removes the database from the filesystem. WARNING: unless you have proper backups or snapshots from your filesystem, this operation is irreversible and leads to permanent data loss.

func (*Database) Vacuum

func (db *Database) Vacuum() error

Vacuum calls Vacuum on all open collections.

type DiskvStorageBackend

type DiskvStorageBackend struct {
	// contains filtered or unexported fields
}

func (*DiskvStorageBackend) Erase

func (s *DiskvStorageBackend) Erase(key string) error

func (*DiskvStorageBackend) Keys

func (s *DiskvStorageBackend) Keys() <-chan string

func (*DiskvStorageBackend) Read

func (s *DiskvStorageBackend) Read(key string) ([]byte, error)

func (*DiskvStorageBackend) Write

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

type Equals

type Equals struct {
	Field string
	Value interface{}
}

type Id

type Id int64

type LevelDBStorageBackend

type LevelDBStorageBackend struct {
	// contains filtered or unexported fields
}

func (*LevelDBStorageBackend) Erase

func (s *LevelDBStorageBackend) Erase(key string) error

func (*LevelDBStorageBackend) Keys

func (s *LevelDBStorageBackend) Keys() <-chan string

func (*LevelDBStorageBackend) Read

func (s *LevelDBStorageBackend) Read(key string) ([]byte, error)

func (*LevelDBStorageBackend) Write

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

type Or

type Or []Condition

type Result

type Result struct {
	// contains filtered or unexported fields
}

func (*Result) Count

func (r *Result) Count() int

func (*Result) First

func (r *Result) First(id *Id, result interface{}) bool

func (*Result) Next

func (r *Result) Next(id *Id, result interface{}) bool

type StorageBackend

type StorageBackend interface {
	Read(key string) ([]byte, error)
	Write(key string, value []byte) error
	Erase(key string) error
	Keys() <-chan string
}

func NewDiskvStorageBackend

func NewDiskvStorageBackend(path string) StorageBackend

func NewLevelDBStorageBackend

func NewLevelDBStorageBackend(path string) StorageBackend

type StorageType

type StorageType string

const (
	STORAGE_AUTO    StorageType = "auto"
	STORAGE_DISKV   StorageType = "diskv"
	STORAGE_LEVELDB StorageType = "leveldb"
)