github.com/portworx/kvdb@v0.0.0-20241107215734-a185a966f535/README.md (about)

     1  # kvdb
     2  
     3  [![GoDoc](https://godoc.org/github.com/portworx/kvdb?status.png)](https://godoc.org/github.com/portworx/kvdb)
     4  [![Travis branch](https://img.shields.io/travis/portworx/kvdb/master.svg)](https://travis-ci.org/portworx/kvdb)
     5  [![Go Report Card](https://goreportcard.com/badge/github.com/portworx/kvdb)](https://goreportcard.com/report/github.com/portworx/kvdb)
     6  [![Code Coverage](https://codecov.io/gh/portworx/kvdb/branch/master/graph/badge.svg)](https://codecov.io/gh/portworx/kvdb)
     7  
     8  Key Value Store abstraction library.
     9  
    10  The kvdb library abstracts the caller from the specific key-value database implementation. The main goal of the kvdb library is to provide simple APIs to deal with only keys and values, and abstract away the intricate details of a specific key value stores. It also provides support for complex APIs like Snapshot, Watch and Lock which are built using the basic APIs.
    11  
    12  ### Supported key value stores
    13  
    14  * `Etcd v2`
    15  * `Etcd v3`
    16  * `Consul`
    17  * `In-memory store` (local to the node)
    18  * `Bolt DB` (local to the node)
    19  * `Zookeeper`
    20  
    21  ### Usage
    22  
    23  The kvdb library is easy to use and requires you to create a new instance of the Kvdb object
    24  
    25  ```
    26  package main
    27  
    28  import (
    29    "github.com/portworx/kvdb"
    30    "github.com/portworx/kvdb/etcd/v3"
    31    "github.com/libopenstorage/openstorage/pkg/dbg"
    32  )
    33  
    34  func getKvdb(
    35    kvdbName string, // Use one of the kv store implementation names
    36    basePath string, // The path under which all the keys will be created by this kv instance
    37    discoveryEndpoints []string,  // A list of kv store endpoints
    38    options map[string]string, // Options that need to be passed to the kv store
    39    panicHandler kvdb.FatalErrorCB, // A callback function to execute when the library needs to panic
    40  ) (kvdb.Kvdb, error) {
    41  
    42  	kv, err := kvdb.New(
    43  		kvdbName,
    44  		basePath,
    45  		discoveryEndpoints,
    46  		options,
    47  		panicHandler,
    48  	)
    49    return kv, err
    50  
    51  }
    52  
    53  type A struct {
    54     a1 string
    55     a2 int
    56  }
    57  
    58  func main() {
    59  
    60    // An example kvdb using etcd v3 as a key value store
    61    kv, err := getKvdb(
    62      v3.Name,
    63      "root/",
    64      []{"127.0.0.1:2379"},
    65      nil,
    66      dbg.Panicf,
    67    )
    68    if err != nil {
    69      fmt.Println("Failed to create a kvdb instance: ", err)
    70      return
    71    }
    72  
    73    // Put a key value pair foo=bar
    74    a := &A{"bar", 1}
    75    _, err = kv.Put("foo", &a, 0)
    76    if err != nil {
    77      fmt.Println("Failed to put a key in kvdb: ", err)
    78      return
    79    }
    80  
    81    // Get a key
    82    value := A{}
    83    _, err = kv.GetVal("foo", &value)
    84    if err != nil {
    85      fmt.Println("Failed to get a key from kvdb: ", err)
    86      return
    87    }
    88  }
    89  
    90  ```
    91  
    92  ### Contributing
    93  
    94  We are always looking for contributions from the open source community. Send out a PR and we will review it.
    95  
    96  
    97  ### Sign your work
    98  
    99  The sign-off is a simple line at the end of the explanation for the
   100  patch, which certifies that you wrote it or otherwise have the right to
   101  pass it on as an open-source patch.  The rules are pretty simple: if you
   102  can certify the below (from
   103  [developercertificate.org](http://developercertificate.org/)):
   104  
   105  ```
   106  Developer Certificate of Origin
   107  Version 1.1
   108  
   109  Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
   110  660 York Street, Suite 102,
   111  San Francisco, CA 94110 USA
   112  
   113  Everyone is permitted to copy and distribute verbatim copies of this
   114  license document, but changing it is not allowed.
   115  
   116  
   117  Developer's Certificate of Origin 1.1
   118  
   119  By making a contribution to this project, I certify that:
   120  
   121  (a) The contribution was created in whole or in part by me and I
   122      have the right to submit it under the open source license
   123      indicated in the file; or
   124  
   125  (b) The contribution is based upon previous work that, to the best
   126      of my knowledge, is covered under an appropriate open source
   127      license and I have the right under that license to submit that
   128      work with modifications, whether created in whole or in part
   129      by me, under the same open source license (unless I am
   130      permitted to submit under a different license), as indicated
   131      in the file; or
   132  
   133  (c) The contribution was provided directly to me by some other
   134      person who certified (a), (b) or (c) and I have not modified
   135      it.
   136  
   137  (d) I understand and agree that this project and the contribution
   138      are public and that a record of the contribution (including all
   139      personal information I submit with it, including my sign-off) is
   140      maintained indefinitely and may be redistributed consistent with
   141      this project or the open source license(s) involved.
   142  ```
   143  
   144  then you just add a line to every git commit message:
   145  
   146      Signed-off-by: Joe Smith <joe@gmail.com>
   147  
   148  using your real name (sorry, no pseudonyms or anonymous contributions.)
   149  
   150  You can add the sign off when creating the git commit via `git commit -s`.
   151  
   152  ### License
   153  
   154  kvdb library is licensed under the Apache License 2.0
   155  
   156  replace google.golang.org/grpc/naming => github.com/xiegeo/grpc-naming v1.29.1-alpha