README
¶
jdb 
A file-backed ACID in-memory k/v data store.
FAQ
Why would I use this over bolt or any other K/V store?
- The data is always in memory, in a very simple memory layout and it is extremely fast.
- You can specify the on-disk file format, the default is JSON, however it is very easy to add your own.
- You can use the values directly in your code without having to copy them*
- You can fully replay the database and discard transactions as needed (not implemented yet).
- modifying values without a copy can result in a race, but the on-disk data won't be corrupted.
- compacting the database will remove older transactions.
Why shouldn't I use this?
Mainly if your dataset doesn't fit in memory then you're better off with an mmap'ed k/v store like the excellent boltdb.
Benchmarks
➤ go test -benchmem -bench=. -v -benchtime=3s
=== RUN TestDB
--- PASS: TestDB (0.00s)
=== RUN TestCryptoBackend
--- PASS: TestCryptoBackend (0.00s)
BenchmarkJDBSameTxReadWriteJSON-8 2000000 2898 ns/op 312 B/op 10 allocs/op
BenchmarkJDBSameTxReadWriteGzipJSON-8 2000000 3027 ns/op 312 B/op 10 allocs/op
BenchmarkJDBSameTxReadWriteCryptoJSON-8 1000000 3077 ns/op 312 B/op 10 allocs/op
BenchmarkJDBSameTxReadWriteCryptoGzipJSON-8 2000000 2908 ns/op 312 B/op 10 allocs/op
BenchmarkBoltSameTxReadWrite-8 500000 8682 ns/op 6309 B/op 44 allocs/op
BenchmarkJDBSeparateReadWriteJSON-8 1000000 3000 ns/op 312 B/op 10 allocs/op
BenchmarkJDBSeparateReadWriteGzipJSON-8 1000000 3014 ns/op 312 B/op 10 allocs/op
BenchmarkJDBSeparateReadWriteCryptoJSON-8 2000000 3020 ns/op 312 B/op 10 allocs/op
BenchmarkJDBSeparateReadWriteCryptoGzipJSON-8 1000000 3000 ns/op 312 B/op 10 allocs/op
BenchmarkBoltSeparateReadWrite-8 500000 16040 ns/op 12416 B/op 53 allocs/op
PASS
ok github.com/OneOfOne/jdb 60.457s
Examples
//db, err := jdb.New(fp, &Opts{Backend: GZipJSONBackend})
db, err := jdb.New("db.jdb", nil) // default JSONBackend
if err != nil {
log.Panic(err)
}
defer db.Close()
err := db.Update(func(tx *Tx) error {
return tx.Set("a", []byte("a")) // or
// return tx.Set("a", jdb.Value("a"))
})
// shorthand for a single
err := db.SetObject("map in a sub-bucket", map[string]bool{
"isCool": true,
}, "parent bucket", "a bucket under the parent bucket")
TODO
- Replay / Filter support.
- Per-bucket unique ID generation.
- Archiving support.
License
Apache v2.0 (see LICENSE file).
Copyright 2016-2016 Ahmed <OneOfOne> W.
Documentation
¶
Index ¶
- Constants
- Variables
- func GZipLevelJSONBackend(level int) func() Backend
- type Backend
- type BucketTx
- func (b *BucketTx) Bucket(name string) *BucketTx
- func (b *BucketTx) Buckets() []string
- func (b *BucketTx) Delete(key string) error
- func (b *BucketTx) DeleteBucket(name string) error
- func (b *BucketTx) ForEach(fn func(key string, val Value) error) error
- func (b *BucketTx) Get(key string) Value
- func (b *BucketTx) GetAll() map[string]Value
- func (b *BucketTx) GetObject(key string, out interface{}) error
- func (b *BucketTx) Set(key string, val Value) error
- func (b *BucketTx) SetObject(key string, val interface{}) error
- type CompactError
- type DB
- func (db *DB) Close() error
- func (db *DB) Compact() error
- func (db *DB) Get(key string, bucket ...string) Value
- func (db *DB) GetObject(key string, out interface{}, bucket ...string) error
- func (db *DB) Name() string
- func (db *DB) Read(fn func(tx *Tx) error) error
- func (db *DB) Set(key string, val []byte, bucket ...string) error
- func (db *DB) SetObject(key string, val interface{}, bucket ...string) error
- func (db *DB) Update(fn func(tx *Tx) error) error
- func (db *DB) View(fn func(tx *Tx) error) error
- type Opts
- type Tx
- type Value
Constants ¶
View Source
const RootBucket = "☢"
Variables ¶
View Source
var ( ErrReadOnly = errors.New("readonly") ErrNotImpl = errors.New("not implemented") ErrNilValue = errors.New("value can't be nil") ErrClosed = errors.New("db is closed, you may access read-only operations") ErrMissingMarshaler = errors.New("missing marshaler") ErrMissingUnmarshaler = errors.New("missing unmarshaler") )
Functions ¶
func GZipLevelJSONBackend ¶
GZipLevelJSONBackend is a shorthand for GZipLevelBackend(JSONBackend(), level)
Types ¶
type Backend ¶
type Backend interface {
Init(w io.Writer, r io.Reader) error // initalizes the backend with a reader/writer, usually just an *os.File
Flush() error // this is called after every transaction
Encode(v interface{}) error // encodes a Tx
Decode(v interface{}) error // decodes a Tx
Marshal(in interface{}) ([]byte, error) // used by SetObject
Unmarshal(in []byte, out interface{}) error // used by GetObject
}
Backend defines a jdb transaction backend the backend may optionally implement the io.Closer interface
func GZipBackend ¶
GZipBackend is an alias for GZipLevelBackend(be, gzip.DefaultCompression)
func GZipJSONBackend ¶
func GZipJSONBackend() Backend
GZipJSONBackend is a shorthand for GZipBackend(JSONBackend())
func GZipLevelBackend ¶
GZipLevelBackend returns a wrapper backend where all the data is gzip'ed.
type BucketTx ¶
type BucketTx struct {
// contains filtered or unexported fields
}
func (*BucketTx) Bucket ¶
Bucket returns a bucket with the specified name, creating it if it doesn't already exist.
func (*BucketTx) DeleteBucket ¶
DeleteBucket opens a portal into a 2D universe full of wonders.
type CompactError ¶
func (*CompactError) Error ¶
func (ce *CompactError) Error() string
type DB ¶
type DB struct {
// contains filtered or unexported fields
}
func (*DB) Compact ¶
Compact compacts the database, transactions will be lost, however the counter will still be valid.
func (*DB) Get ¶
Get is a shorthand access a value in an optional bucket chain.
Example: v := db.Get("name", "users", "user-id-1")
Source Files
Directories
Click to show internal directories.
Click to hide internal directories.