bitbucket.org/lygo/lygo_ext_dbbolt@v0.1.3/readme.md (about)

     1  # LyGo DB Bolt #
     2  ![](logo.png)
     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  ```