vendor/github.com/hashicorp/go-memdb/README.md

   1 # go-memdb
   2
   3 Provides the `memdb` package that implements a simple in-memory database
   4 built on immutable radix trees. The database provides Atomicity, Consistency
   5 and Isolation from ACID. Being that it is in-memory, it does not provide durability.
   6 The database is instantiated with a schema that specifies the tables and indicies
   7 that exist and allows transactions to be executed.
   8
   9 The database provides the following:
  10
  11 * Multi-Version Concurrency Control (MVCC) - By leveraging immutable radix trees
  12   the database is able to support any number of concurrent readers without locking,
  13   and allows a writer to make progress.
  14
  15 * Transaction Support - The database allows for rich transactions, in which multiple
  16   objects are inserted, updated or deleted. The transactions can span multiple tables,
  17   and are applied atomically. The database provides atomicity and isolation in ACID
  18   terminology, such that until commit the updates are not visible.
  19
  20 * Rich Indexing - Tables can support any number of indexes, which can be simple like
  21   a single field index, or more advanced compound field indexes. Certain types like
  22   UUID can be efficiently compressed from strings into byte indexes for reduces
  23   storage requirements.
  24
  25 For the underlying immutable radix trees, see [go-immutable-radix](https://github.com/hashicorp/go-immutable-radix).
  26
  27 Documentation
  28 =============
  29
  30 The full documentation is available on [Godoc](http://godoc.org/github.com/hashicorp/go-memdb).
  31
  32 Example
  33 =======
  34
  35 Below is a simple example of usage
  36
  37 ```go
  38 // Create a sample struct
  39 type Person struct {
  40     Email string
  41     Name  string
  42     Age   int
  43 }
  44
  45 // Create the DB schema
  46 schema := &memdb.DBSchema{
  47     Tables: map[string]*memdb.TableSchema{
  48         "person": &memdb.TableSchema{
  49             Name: "person",
  50             Indexes: map[string]*memdb.IndexSchema{
  51                 "id": &memdb.IndexSchema{
  52                     Name:    "id",
  53                     Unique:  true,
  54                     Indexer: &memdb.StringFieldIndex{Field: "Email"},
  55                 },
  56             },
  57         },
  58     },
  59 }
  60
  61 // Create a new data base
  62 db, err := memdb.NewMemDB(schema)
  63 if err != nil {
  64     panic(err)
  65 }
  66
  67 // Create a write transaction
  68 txn := db.Txn(true)
  69
  70 // Insert a new person
  71 p := &Person{"joe@aol.com", "Joe", 30}
  72 if err := txn.Insert("person", p); err != nil {
  73     panic(err)
  74 }
  75
  76 // Commit the transaction
  77 txn.Commit()
  78
  79 // Create read-only transaction
  80 txn = db.Txn(false)
  81 defer txn.Abort()
  82
  83 // Lookup by email
  84 raw, err := txn.First("person", "id", "joe@aol.com")
  85 if err != nil {
  86     panic(err)
  87 }
  88
  89 // Say hi!
  90 fmt.Printf("Hello %s!", raw.(*Person).Name)
  91
  92 ```
  93