NOTE: This is a prerelease. The API may change.
Filebase
Version v0.1.0-alpha
Filebase is a filesystem based Key-Object store with plugable codec.
Why?
Filebase is ideal when you want more than config files yet not a database. Because Filebase is using filesystem and optionally human readable encoding, you can work with the database with traditional text editing tools like a GUI texteditor or commandline tools like cat
,grep
,head
, et all, it also means you can selectivly backup your data.
Codecs
Filebase currently ships YAML, JSON, and gob codecs.
To build a new codec, you just need to satisify the codec.Codec
interface:
type Codec interface {
NewDecoder(io.Reader) decoder
NewEncoder(io.Writer) encoder
}
type decoder interface {
Decode(v interface{}) error
}
type encoder interface {
Encode(v interface{}) error
}
Bucket & Objects
Filebase has no concept of table or database, it is buckets and objects. A bucket may have any number of object and bucket to the limits supported by the underlying file system.
TODO:
- Finish this readme.
- Add example.
- More test for Bucket.Query
filebase
--
API Reference:
Constants
const (
ObjectPerm os.FileMode = 0640
BucketPerm os.FileMode = 0750
)
Variables
var (
ErrorKeyEmpty = fault{"Empty Key.", ""}
ErrorNotObjectKey = fault{"Key %s is a bucket.", ""}
ErrorLocationEmpty = fault{"Location Empty.", ""}
)
You should expect the following errors. the fault is an error type so you should treat them like so.
type Bucket
type Bucket struct {
}
A Buck is an structure that holds objects and bucks. It is a directory on filesystem.
func New
func New(location string, codec codec.Codec) *Bucket
Returns a new bucket object, it does not touch the underlying filesystem if it already exists. The codec is used for Marshling and Unmarshaling Objects. Currently there is, codec.YAML, codec.JSON, codec.GOB. To add your own. see https://godoc.org/github.com/omeid/filebase/codec.
func (*Bucket) Bucket
func (c *Bucket) Bucket(name string) *Bucket
Returns a buck with the 'name' under current bucket. It creates a new bucket if it doesn't exists.
func (*Bucket) Buckets
func (c *Bucket) Buckets(query string, sort bool) ([]string, error)
Returns a list of buckets in the current bucket that matches the query. The syntax is same as Objects.
func (*Bucket) Destroy
func (c *Bucket) Destroy(force bool) error
Deletes the bucket and returns error on failur. It will fail on non-empty buckets unless force is set to true.
func (*Bucket) Error
func (c *Bucket) Error() error
func (*Bucket) Get
func (c *Bucket) Get(key string, out interface{}) error
Get returns an Object from the bucket and unmarshals it into out
Fails on
decoding failur.
func (*Bucket) Name
func (c *Bucket) Name() string
Returns the backet name. It is same as the directory name on filesystem level.
func (*Bucket) Objects
func (c *Bucket) Objects(query string, sort bool) ([]string, error)
func (*Bucket) Put
func (c *Bucket) Put(key string, data interface{}, unique bool, sync bool) error
Puts a new object into the bucket. An object can be any Go type, you may need to add approprate tags to your object type according to the codec used. If unique is set, it will fail if a key already exists. It will ask the underlying system to sync if sync is set to true. Object is stored under the same name in filesystem.
func (*Bucket) Query
func (c *Bucket) Query(bucketQuery string, objectQuery string, sort bool) (Result, error)
Query returns a Result object that hold keys and buckets that filter. The syntax is same as Objects and Buckets. It only looks for objects that matches the objectQuery in backs that matchs the bucketQuery. It returns error on invalid query.
type Result
type Result struct {
Objects []string
Buckets map[string]Result
}
The Result is a tree structure that is returned by Query.