sod

package module
v1.6.9 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 2, 2022 License: GPL-3.0 Imports: 17 Imported by: 0

README

Version GoDoc Build Coverage

Go Simple Object Database

A simple database model to store Go structure (on disk) and search across them. It has features close to what an ORM framework can provide but has the advantage of being:

  • in pure Go (de facto portable)
  • does not depend on any DB engine (SQL, SQLite, Mongo ...) to do its job
  • everything is kept simple (one file per structure and eventually an index) It supports structure fields indexing to speed up searches on important fields.

What should you use this project for:

  • you want to implement Go struct persistency in a simple way
  • you want to do DB like operations on those structures (Update, Delete, Search ...)
  • you don't want to deploy an ORM framework

What you should not use this project for:

  • even though performances are not so bad, I don't think you can rely on it for high troughput DB operations

Examples

See examples directory for all examples.

Documentation

Index

Constants

View Source 
const (
	SchemaFilename = "schema.json"
)

Variables

View Source 
var (
	ErrUnkownField          = errors.New("unknown object field")
	ErrFieldNotIndexed      = errors.New("field not indexed")
	ErrFieldUnique          = errors.New("unique constraint on field")
	ErrUnkownSearchOperator = errors.New("unknown search operator")
)
View Source 
var (
	ErrBadSchema       = errors.New("schema must be a file")
	ErrMissingObjIndex = errors.New("schema is missing object index")

	DefaultSchema = Schema{Extension: ".json"}
)
View Source 
var (
	ErrUnknownOperator = errors.New("unknown logical operator")
	ErrNoObjectFound   = errors.New("no object found")
)
View Source 
var (
	DefaultPermissions = fs.FileMode(0700)
	LowercaseNames     = true
)
View Source 
var (
	ErrEOI = errors.New("end of iterator")
)
View Source 
var (
	ErrInvalidObject = errors.New("object is not valid")
)
View Source 
var (
	ErrUnknownKeyType = errors.New("unknown key type")
)

Functions

func CamelToSnake added in v1.6.0 

func CamelToSnake(camel string) string

func IsNoObjectFound added in v1.3.0 

func IsNoObjectFound(err error) bool

func IsUnique added in v1.3.0 

func IsUnique(err error) bool

func NewFieldIndex 

func NewFieldIndex(desc FieldDescriptor, opts ...int) *fieldIndex

NewFieldIndex returns an empty initialized slice. Opts takes len and cap in order to initialize the underlying slice

func ToObjectChan added in v1.6.1 

func ToObjectChan(slice interface{}) (objs chan Object)

ToObjectChan is a convenient function to pre-process arguments passed to InsertOrUpdateMany function.

func UnmarshalJsonFile 

func UnmarshalJsonFile(path string, i interface{}) (err error)

func ValidationErr added in v1.6.1 

func ValidationErr(o Object, err error) error

Types

type Async added in v1.5.0 

type Async struct {
	Enable    bool
	Threshold int
	Timeout   time.Duration
	// contains filtered or unexported fields
}

func (*Async) MarshalJSON added in v1.5.0 

func (a *Async) MarshalJSON() ([]byte, error)

func (*Async) UnmarshalJSON added in v1.5.0 

func (a *Async) UnmarshalJSON(b []byte) (err error)

type Constraints added in v1.4.0 

type Constraints struct {
	Unique bool `json:"unique"`
}

type DB 

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

func Open 

func Open(root string) *DB

Open opens a Simple Object Database

func (*DB) All 

func (db *DB) All(of Object) (out []Object, err error)

All returns all Objects in the DB

func (*DB) Close 

func (db *DB) Close() (last error)

Close closes gently the DB by flushing any pending async writes and by committing all the schemas to disk

func (*DB) Commit 

func (db *DB) Commit(o Object) (err error)

Commit object schema on the disk. This method must be called after Insert/Delete operations.

func (*DB) Control added in v1.4.0 

func (db *DB) Control() (err error)

Control controls checks for inconsistencies in DB

func (*DB) Count 

func (db *DB) Count(of Object) (n int, err error)

Count the number of Object in the database

func (*DB) Create 

func (db *DB) Create(o Object, s Schema) (err error)

Create a schema for an Object

func (*DB) Delete 

func (db *DB) Delete(o Object) (lastErr error)

Delete deletes a single Object from the database and commit changes

func (*DB) DeleteAll 

func (db *DB) DeleteAll(of Object) (err error)

DeleteAll deletes all Objects of the same type and commit changes

func (*DB) DeleteObjects added in v1.4.0 

func (db *DB) DeleteObjects(from *Iterator) (err error)

DeleteObjects deletes Objects from an Iterator and commit changes. This primitive can be used for bulk deletions.

func (*DB) Drop 

func (db *DB) Drop() (err error)

Drop drops all the database

func (*DB) Exist 

func (db *DB) Exist(o Object) (ok bool, err error)

Exist returns true if the object exist.

func (*DB) Flush added in v1.5.0 

func (db *DB) Flush(o Object) (err error)

Flush a single object to disk. Flush does not commit schema

func (*DB) FlushAll added in v1.5.0 

func (db *DB) FlushAll(of Object) (err error)

FlushAll objects of type to disk. As Flush this function does not commit schema to disk

func (*DB) FlushAllAndCommit added in v1.6.6 

func (db *DB) FlushAllAndCommit(of Object) (last error)

FlushAllAndCommit flushes objects of type to disk and commit schema

func (*DB) FlushAndCommit added in v1.6.6 

func (db *DB) FlushAndCommit(o Object) (last error)

Flush a single object to disk and commit changes

func (*DB) Get 

func (db *DB) Get(in Object) (out Object, err error)

Get gets a single Object from the DB

func (*DB) GetByUUID added in v1.6.5 

func (db *DB) GetByUUID(in Object, uuid string) (out Object, err error)

GetByUUID gets a single Object from the DB its UUID

func (*DB) InsertOrUpdate 

func (db *DB) InsertOrUpdate(o Object) (err error)

InsertOrUpdate inserts or updates a single Object and commits changes. This method is not suited for bulk insertions as each insert will trigger a write overhead. For bulk insertion use InsertOrUpdateBulk function

func (*DB) InsertOrUpdateBulk 

func (db *DB) InsertOrUpdateBulk(in chan Object, csize int) (err error)

InsertOrUpdateBulk inserts objects in bulk in the DB. A chunk size needs to be provided to commit the DB at every chunk. The DB is locked at every chunk processed, so changing the chunk size impact other concurrent DB operations.

func (*DB) InsertOrUpdateMany added in v1.5.0 

func (db *DB) InsertOrUpdateMany(objects ...Object) (err error)

InsertOrUpdateMany inserts several objects into the DB and commit schema after all insertions. It is faster than calling InsertOrUpdate for every objects separately.

func (*DB) Iterator 

func (db *DB) Iterator(of Object) (it *Iterator, err error)

Iterator returns an Object Iterator

func (*DB) Lock added in v1.5.0 

func (db *DB) Lock()

func (*DB) RLock added in v1.5.0 

func (db *DB) RLock()

func (*DB) RUnlock added in v1.5.0 

func (db *DB) RUnlock()

func (*DB) Schema 

func (db *DB) Schema(of Object) (s *Schema, err error)

Schema retrieves the schema of an Object

func (*DB) Search 

func (db *DB) Search(o Object, field, operator string, value interface{}) *Search

Search Object where field matches value according to an operator

func (*DB) Unlock added in v1.5.0 

func (db *DB) Unlock()

type FieldDescriptor added in v1.3.0 

type FieldDescriptor struct {
	Name       string      `json:"-"`
	Index      bool        `json:"-"`
	Constraint Constraints `json:"constraint"`
}

type Index 

type Index struct {
	Fields map[string]*fieldIndex
	// mapping ObjectId -> Object UUID
	ObjectIds map[uint64]string
	// contains filtered or unexported fields
}

func NewIndex 

func NewIndex(fields ...FieldDescriptor) *Index

func (*Index) Control added in v1.4.0 

func (in *Index) Control() error

func (*Index) Delete 

func (in *Index) Delete(o Object)

func (*Index) InsertOrUpdate 

func (in *Index) InsertOrUpdate(o Object) (err error)

func (*Index) Len 

func (in *Index) Len() int

func (*Index) MarshalJSON 

func (in *Index) MarshalJSON() ([]byte, error)

func (*Index) SatisfyAll added in v1.4.0 

func (in *Index) SatisfyAll(o Object) (err error)

func (*Index) Search 

func (in *Index) Search(o Object, field string, operator string, value interface{}, constrain []*IndexedField) ([]*IndexedField, error)

func (*Index) UnmarshalJSON 

func (in *Index) UnmarshalJSON(data []byte) error

type IndexedField 

type IndexedField struct {
	// the value we want to index
	Value interface{}
	// the ObjectId of the object in the list of object
	// it must be unique accross one ObjectId
	ObjectId uint64
}

func NewIndexedField 

func NewIndexedField(value interface{}, objid uint64) (*IndexedField, error)

func (*IndexedField) DeepEqual 

func (f *IndexedField) DeepEqual(other *IndexedField) bool

func (*IndexedField) Equal 

func (f *IndexedField) Equal(other *IndexedField) bool

func (*IndexedField) Evaluate 

func (f *IndexedField) Evaluate(operator string, other *IndexedField) bool

func (*IndexedField) Greater 

func (f *IndexedField) Greater(other *IndexedField) bool

func (*IndexedField) Less 

func (f *IndexedField) Less(other *IndexedField) bool

func (*IndexedField) MarshalJSON 

func (f *IndexedField) MarshalJSON() ([]byte, error)

func (*IndexedField) String 

func (f *IndexedField) String() string

func (*IndexedField) UnmarshalJSON 

func (f *IndexedField) UnmarshalJSON(data []byte) error

func (*IndexedField) ValueTypeFromString 

func (f *IndexedField) ValueTypeFromString(t string)

func (*IndexedField) ValueTypeString 

func (f *IndexedField) ValueTypeString() string

type Item 

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

Item is a base structure implementing Object interface

func (*Item) Initialize 

func (o *Item) Initialize(uuid string)

func (*Item) Transform added in v1.6.2 

func (o *Item) Transform()

func (*Item) UUID 

func (o *Item) UUID() string

func (*Item) Validate added in v1.6.1 

func (o *Item) Validate() error

type Iterator 

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

func (*Iterator) Len 

func (it *Iterator) Len() int

func (*Iterator) Next 

func (it *Iterator) Next() (o Object, err error)

func (*Iterator) Reverse added in v1.2.0 

func (it *Iterator) Reverse() *Iterator

type Object 

type Object interface {
	// UUID returns a unique identifier used to store the
	// Object in the database
	UUID() string

	// Initialize is called to initialize the UUID associated
	// to an Object
	Initialize(string)

	// Transform is called prior to Object insertion and
	// can be used to apply some transformation on the data
	// to insert.
	Transform()

	// Validate is called every time an Object is inserted
	// if an error is returned by this function the Object
	// will not be inserted.
	Validate() error
}

func ToObjectSlice added in v1.5.1 

func ToObjectSlice(slice interface{}) (objs []Object)

ToObjectSlice is a convenient function to pre-process arguments passed to InsertOrUpdateMany function.

type Schema 

type Schema struct {
	Extension    string `json:"extension"`
	Cache        bool   `json:"cache"`
	AsyncWrites  *Async `json:"async-writes,omitempty"`
	ObjectsIndex *Index `json:"index"`
	// contains filtered or unexported fields
}

func (*Schema) Asynchrone added in v1.6.3 

func (s *Schema) Asynchrone(threshold int, timeout time.Duration)

Asynchrone makes the data described by this schema managed asynchronously Objects will be written either if more than threshold events are modified or at every timeout

func (*Schema) Index 

func (s *Schema) Index(o Object) error

Index indexes an Object

func (*Schema) Initialize 

func (s *Schema) Initialize(o Object)

func (*Schema) Unindex 

func (s *Schema) Unindex(o Object)

Index un-indexes an Object 

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

Search helper structure to easily build search queries on objects and retrieve the results

func (*Search) And 

func (s *Search) And(field, operator string, value interface{}) *Search

And performs a new Search while "ANDing" search results

func (*Search) AssignOne added in v1.6.8 

func (s *Search) AssignOne(target interface{}) (err error)

AssignOne returns the first result found calling Collect function and assign the Object found to target. Target must be a *sod.Object otherwise the function panics. If no Object is found, ErrNoObjectFound is returned

func (*Search) Collect 

func (s *Search) Collect() (out []Object, err error)

Collect all the objects resulting from the search. If a search has been made on an indexed field, results will be in descending order by default. If you want to change result order, call Reverse before. NB: only search on indexed field(s) will be garanteed to be ordered according to the last field searched.

func (*Search) Delete added in v1.4.0 

func (s *Search) Delete() (err error)

Delete deletes the objects found by the search

func (*Search) Err 

func (s *Search) Err() error

Err return any error encountered while searching

func (*Search) Iterator 

func (s *Search) Iterator() (it *Iterator, err error)

Iterator returns an Iterator convenient to iterate over the objects resulting from the search

func (*Search) Len 

func (s *Search) Len() int

Len returns the number of data returned by the search

func (*Search) Limit added in v1.2.0 

func (s *Search) Limit(limit uint64) *Search

Limit the number of results collected by Collect function

func (*Search) One added in v1.3.0 

func (s *Search) One() (o Object, err error)

One returns the first result found calling Collect function. If no Object is found, ErrNoObjectFound is returned

func (*Search) Operation added in v1.6.3 

func (s *Search) Operation(operator, field, comparator string, value interface{}) *Search

Operation performs a new Search while ANDing or ORing the results operator must be in ["and", "&&", "or", "||"]

func (*Search) Or 

func (s *Search) Or(field, operator string, value interface{}) *Search

Or performs a new Search while "ORing" search results

func (*Search) Reverse added in v1.1.0 

func (s *Search) Reverse() *Search

Reverse the order the results are collected by Collect function

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.