Lightweight document-oriented NoSQL Database

English | 简体中文 | Spanish

CloverDB is a lightweight NoSQL database designed for being simple and easily maintainable, thanks to its small code base. It has been inspired by tinyDB.

Features

• Document oriented
• Written in pure Golang
• Simple and intuitive api
• Easily maintainable

Why CloverDB?

CloverDB has been written for being easily maintenable. As such, it trades performance with simplicity, and is not intented to be an alternative to more performant databases such as MongoDB or MySQL. However, there are projects where running a separate database server may result overkilled, and, for simple queries, network delay may be the major performance bottleneck. For there scenario, CloverDB may be a more suitable alternative.

Database layout

CloverDB abstracts the way collections are stored on disk through the StorageEngine interface. The default implementation is based on the Badger database key-value store. However, you could easily write your own storage engine implementation.

Installation

Make sure you have a working Go environment (Go 1.13 or higher is required).

  go get github.com/ostafen/clover

API usage

import (
	"log"
	c "github.com/ostafen/clover"
)

...

Create a new collection

db, _ := c.Open("clover-db")
db.CreateCollection("myCollection")

doc := c.NewDocument()
doc.Set("hello", "clover!")

docId, _ := db.InsertOne("myCollection", doc)

doc, _ = db.Query("myCollection").FindById(docId)
log.Println(doc.Get("hello"))

Query an existing database

db, _ := c.Open("../test-data/todos")

// find all completed todos belonging to users with id 5 and 8
docs, _ := db.Query("todos").Where(c.Field("completed").Eq(true).And(c.Field("userId").In(5, 8))).FindAll()

todo := &struct {
    Completed bool   `json:"completed"`
    Title     string `json:"title"`
    UserId    int    `json:"userId"`
}{}

for _, doc := range docs {
    doc.Unmarshal(todo)
    log.Println(todo)
}

Update and delete documents

db, _ := c.Open("../test-data/todos")

// mark all todos belonging to user with id 1 as completed
updates := make(map[string]interface{})
updates["completed"] = true

db.Query("todos").Where(c.Field("userId").Eq(1)).Update(updates)

// delete all todos belonging to users with id 5 and 8
db.Query("todos").Where(c.Field("userId").In(5,8)).Delete()

Update a single document

db, _ := c.Open("../test-data/todos")

updates := make(map[string]interface{})
updates["completed"] = true

// you can either obtain the _id
doc, _ := db.Query("todos").Where(c.Field("userId").Eq(2)).FindFirst()
docId := doc.Get("_id")

// or using a string
// docId := "1dbce353-d3c6-43b3-b5a8-80d8d876389b"

// update a single document with the _id field
db.Query("todos").Where(c.Field("_id").Eq(docId)).Update(updates)

Contributing

CloverDB is actively developed. Any contribution, in the form of a suggestion, bug report or pull request, is well accepted 😊