bitbucket.org/lygo/lygo_ext_dbbolt@v0.1.3/readme.md (about) 1 # LyGo DB Bolt # 2  3 ## Introduction to BBolt ## 4 5 6 Bolt is a pure Go key/value store inspired by [Howard Chu's](https://twitter.com/hyc_symas) 7 [LMDB project](http://symas.com/mdb/). 8 9 The goal of the project is to provide a simple, fast, and reliable database for projects that don't 10 require a full database server such as Postgres or MySQL. 11 12 [BBolt](https://pkg.go.dev/go.etcd.io/bbolt/) supports fully serializable transactions, ACID semantics, and lock-free 13 MVCC with multiple readers and a single writer. 14 Bolt can be used for projects that want a simple data store without the need to add large 15 dependencies such as Postgres or MySQL. 16 17 Bolt is a single-level, zero-copy, B+tree data store. This means that Bolt is optimized for fast read access and does 18 not require recovery in the event of a system crash. Transactions which have not finished committing will simply be 19 rolled back in the event of a crash. 20 21 The design of Bolt is based on Howard Chu's LMDB database project. 22 Bolt currently works on Windows, Mac OS X, and Linux. 23 24 ### Basics ### 25 26 There are only a few types in Bolt: DB, Bucket, Tx, and Cursor. 27 The DB is a collection of buckets and is represented by a single file on disk. 28 A bucket is a collection of unique keys that are associated with values. 29 30 Transactions provide either read-only or read-write access to the database. 31 Read-only transactions can retrieve key/value pairs and can use Cursors to iterate over the dataset sequentially. 32 Read-write transactions can create and delete buckets and can insert and remove keys. 33 Only one read-write transaction is allowed at a time. 34 35 ## LyGo DB Bolt ## 36 37 LyGo BBolt is a wrapper implementation that allow use BBolt with a simple implementation. 38 39 ``` 40 // create and open DB 41 db := lygo_ext_dbbolt.NewBoltDatabase(config) 42 err = db.Open() 43 44 // get/create collection 45 coll, err := db.Collection("big-coll", true) 46 47 // insert/update item 48 item := &map[string]interface{}{ 49 "_key": "1", 50 "name": "Mario", 51 "age": 22, 52 } 53 err = coll.Upsert(item) 54 ``` 55 56 LyGo implementation assume that document's key is named "_key". 57 58 ## Use LyGo DB Bolt for Cache ## 59 60 ``` 61 filename := "./db/expiring.dat" 62 _ = lygo_paths.Mkdir(filename) 63 config := lygo_ext_dbbolt.NewBoltConfig() 64 config.Name = filename 65 66 db := lygo_ext_dbbolt.NewBoltDatabase(config) 67 err := db.Open() 68 if nil!=err{ 69 panic(err) 70 } 71 72 defer db.Close() 73 74 coll, err := db.Collection("cache", true) 75 if nil!=err{ 76 panic(err) 77 } 78 79 // set collection as expirable 80 coll.EnableExpire(true) 81 82 // add an expirable item to collection 83 item := map[string]interface{}{ 84 "_key": lygo_rnd.Uuid(), 85 "name": "NAME " + lygo_strings.Format("%s", i), 86 } 87 item[lygo_ext_dbbolt.FieldExpire] = time.Now().Add(5 * time.Second).Unix() 88 err = coll.Upsert(item) 89 90 if nil!=err{ 91 panic(err) 92 } 93 94 ``` 95 96 LyGo DB Bolt can be used as a temporary cache repository because has a feature that 97 automatically deletes data whose expiration time has reached. 98 99 To enable a collection to check items for timed expiration you need: 100 101 * Enable a collection to check for expired fields 102 * Add "_expire" field to collection (use constant "lygo_ext_dbbolt.FieldExpire") 103 104 ``` 105 // set collection as expirable 106 coll.EnableExpire(true) 107 108 ... 109 110 // add "_expire" field 111 item[lygo_ext_dbbolt.FieldExpire] = time.Now().Add(5 * time.Second).Unix() 112 ``` 113 114 `_expire` field must be a unix timestamp, an int64 value. 115 116 ## When to Use LyGo DB Bolt ## 117 118 LyGo DB Bolt is great when you need a full embeddable cross platform key-value pair database. 119 120 Mongo, Arango Redis and so on are a fair way greater than LyGo Bolt, but are not embeddable and fully cross platform 121 like pure Go code is. LyGo Bolt is just pure Go code. 122 123 124 125 ## How to Use ## 126 127 To use just call: 128 129 `go get -u bitbucket.org/lygo/lygo_ext_dbbolt` 130 131 ## Dependencies ## 132 133 ``` 134 go get -u bitbucket.org/lygo/lygo_commons 135 go get -u bitbucket.org/lygo/lygo_events 136 137 go get -u go.etcd.io/bbolt/... 138 ``` 139 140 This module depends on [bbolt](https://github.com/etcd-io/bbolt) 141 and some LyGo Modules. 142 143 ### Versioning ### 144 145 Sources are versioned using git tags: 146 147 ``` 148 git tag v0.1.3 149 git push origin v0.1.3 150 ```