clover

<p align="center"> <img alt="CloverDB 标志" src="https://raw.githubusercontent.com/ostafen/clover/v2/.github/logo.png#gh-light-mode-only" width="300px"> <img alt="CloverDB 标志" src="https://raw.githubusercontent.com/ostafen/clover/v2/.github/logo-white.png#gh-dark-mode-only" width="300px"> </p> <h2 align="center">轻量级面向文档的 NoSQL 数据库</h2>

🇬🇧 英文 | 🇨🇳 简体中文 | 🇪🇸 西班牙语

CloverDB 是一个轻量级 NoSQL 数据库，由于其代码库小巧，设计简单易于维护。它的灵感来自 tinyDB。

特点

• 面向文档
• 纯 Golang 编写
• 简单直观的 API
• 易于维护

为什么选择 CloverDB？

CloverDB 的编写目的是易于维护。因此，它在性能和简单性之间做了权衡，并不打算成为像 MongoDB 或 MySQL 这样更高性能数据库的替代品。 然而，有些项目中运行单独的数据库服务器可能会显得有些过度，而且对于简单查询来说，网络延迟可能是主要的性能瓶颈。 在这些场景下，CloverDB 可能是一个更合适的选择。

数据库布局

之前，CloverDB 依赖 Badger 键值存储作为存储层。然而，Badger 并不适用于所有场景（例如，当数据库大小受限时）。因此，CloverDB 的存储层通过一组接口类型进行了抽象，以便与任何键值存储一起工作。目前，CloverDB 可以同时使用 Badger 和 Bolt（默认使用 Bolt）。

安装

确保你有一个可用的 Go 环境（需要 Go 1.18 或更高版本）。

  GO111MODULE=on go get github.com/ostafen/clover/v2

数据库和集合

CloverDB 将数据记录存储为 JSON 文档，这些文档在集合中组织在一起。一个数据库由一个或多个集合组成。

数据库

要在集合中存储文档，你需要使用 Open() 函数打开一个 Clover 数据库。

import (
  "log"
  "github.com/dgraph-io/badger/v4"
  c "github.com/ostafen/clover"
  badgerstore "github.com/ostafen/clover/v2/store/badger"
)

...

// 默认情况下，将内部使用 Bolt
db, _ := c.Open("clover-db")

// 如果你想选择不同的存储后端，请使用 OpenWithStore()
store, _ := badgerstore.Open(badger.DefaultOptions("").WithInMemory(true)) // 打开一个 badger 内存数据库
db, _ := c.OpenWithStore(store)

defer db.Close() // 记得在完成后关闭数据库

集合

CloverDB 将文档存储在集合中。集合是关系数据库中表的无模式等价物。可以通过在数据库实例上调用 CreateCollection() 函数来创建集合。可以使用 Insert() 或 InsertOne() 方法插入新文档。每个文档由存储在 _id 特殊字段中的版本 4 UUID 唯一标识，该 UUID 在插入时生成。

db, _ := c.Open("clover-db")
db.CreateCollection("myCollection") // 创建一个名为 "myCollection" 的新集合

// 在集合中插入一个新文档
doc := c.NewDocument()
doc.Set("hello", "clover!")

// InsertOne 返回插入文档的 id
docId, _ := db.InsertOne("myCollection", doc)
fmt.Println(docId)

导入和导出集合

无论使用何种存储引擎，CloverDB 都能轻松地将集合导入和导出为 JSON 格式。

// 将 "todos" 集合的内容导出到 "todos.json" 文件
db.ExportCollection("todos", "todos.json")

...

// 从导出的 json 文件恢复 todos 集合
db.DropCollection("todos")
db.ImportCollection("todos", "todos.json")

docs, _ := db.FindAll(c.NewQuery("todos"))
for _, doc := range docs {
  log.Println(doc)
}

查询

CloverDB 配备了一个流畅优雅的 API 来查询你的数据。查询由 Query 对象表示，它允许检索匹配给定条件的文档。可以通过将有效的集合名称传递给 Query() 方法来创建查询。

选择集合中的所有文档

FindAll() 方法用于检索满足给定查询的所有文档。

docs, _ := db.FindAll(c.NewQuery("myCollection"))

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

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

使用条件筛选文档

为了筛选 FindAll() 返回的文档，你需要使用 Where() 方法指定查询条件。条件对象简单地表示文档上的谓词，只有当文档满足所有查询条件时才评估为真。

以下示例展示了如何构建一个简单的条件，匹配所有 completed 字段等于 true 的文档。

db.FindAll(c.NewQuery("todos").Where(c.Field("completed").Eq(true)))

// 或等效地
db.FindAll(c.NewQuery("todos").Where(c.Field("completed").IsTrue()))

为了构建非常复杂的查询，我们通过使用 And() 和 Or() 方法链接多个条件对象，每个方法返回一个通过应用相应逻辑运算符获得的新条件。

// 查找所有已完成的待办事项，属于 id 为 5 和 8 的用户
db.FindAll(c.NewQuery("todos").Where(c.Field("completed").Eq(true).And(c.Field("userId").In(5, 8))))

当然，你也可以创建涉及多个字段的条件。CloverDB 为你提供了两种等效的方式来实现这一点：

db.FindAll(c.NewQuery("myCollection").Where(c.Field("myField1").Gt(c.Field("myField2"))))
// 或者，如果你喜欢
db.FindAll(c.NewQuery("myCollection").Where(c.Field("myField1").Gt("$myField2")))

排序文档

要在 CloverDB 中排序文档，你需要使用 Sort()。它是一个可变参数函数，接受一系列 SortOption，每个 SortOption 允许指定一个字段和排序方向。 排序方向可以是 1 或 -1，分别对应升序和降序。如果没有提供 SortOption，Sort() 默认使用 _id 字段。

// 查找属于最近插入用户的任何待办事项
db.FindFirst(c.NewQuery("todos").Sort(c.SortOption{"userId", -1}))

跳过/限制文档

有时，舍弃一些文档或者简单地限制查询返回的最大结果数量可能会很有用。为此，CloverDB提供了Skip()和Limit()函数，它们都接受一个整数$n$作为参数。

// 从输出中舍弃前10个文档，
// 同时将查询结果的最大数量限制为100
db.FindAll(c.NewQuery("todos").Skip(10).Limit(100))

更新/删除文档

Update()方法用于修改集合中文档的特定字段。Delete()方法用于删除文档。这两种方法都属于Query对象，因此可以轻松更新和删除匹配特定查询的文档。

// 将id为1的用户的所有待办事项标记为已完成
updates := make(map[string]interface{})
updates["completed"] = true

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

// 删除id为5和8的用户的所有待办事项
db.Delete(c.NewQuery("todos").Where(c.Field("userId").In(5,8)))

要使用特定文档id更新或删除单个文档，请分别使用UpdateById()或DeleteById()：

docId := "1dbce353-d3c6-43b3-b5a8-80d8d876389b"
// 更新指定id的文档
db.UpdateById("todos", docId, map[string]interface{}{"completed": true})
// 或删除它
db.DeleteById("todos", docId)

索引

在CloverDB中，索引支持高效执行查询。没有索引，必须完全扫描集合以选择匹配给定查询的文档。索引是一种特殊的数据结构，存储特定文档字段（或字段集）的值，按字段值本身排序。这意味着它们可以被利用来支持高效的相等匹配和基于范围的查询。 此外，当通过索引迭代文档时，可以按排序顺序返回结果，而无需执行任何额外的排序步骤。 但请注意，使用索引并非完全免费。除了增加磁盘空间外，索引在每次插入和更新/删除操作期间还需要额外的CPU时间。此外，通过索引访问文档时，必须执行两次磁盘读取，因为索引只存储对实际文档的引用（文档id）。因此，只有当指定的条件用于访问有限的文档集时，加速效果才显著。

创建索引

目前，CloverDB仅支持单字段索引。可以通过调用CreateIndex()方法创建索引，该方法接受集合名称和要索引的字段名称。

db.CreateIndex("myCollection", "myField")

假设你有以下查询：

criteria := c.Field("myField").Gt(a).And(c.Field("myField").Lt(b))
db.FindAll(c.NewQuery("myCollection").Where(criteria).Sort(c.SortOption{"myField", -1}))

其中a和b是你选择的值。CloverDB将使用创建的索引来执行范围查询并按排序顺序返回结果。

数据类型

在内部，CloverDB支持以下基本数据类型：int64、uint64、float64、string、bool和time.Time。在可能的情况下，具有不同类型的值会被静默转换为内部类型之一：有符号整数值被转换为int64，而无符号整数值被转换为uint64。Float32值被扩展为float64。

例如，考虑以下代码片段，它在给定文档字段上设置一个uint8值：

doc := c.NewDocument()
doc.Set("myField", uint8(10)) // "myField"自动提升为uint64

fmt.Println(doc.Get("myField").(uint64))

指针值被解引用，直到找到nil或非指针值：

var x int = 10
var ptr *int = &x
var ptr1 **int = &ptr

doc.Set("ptr", ptr)
doc.Set("ptr1", ptr1)

fmt.Println(doc.Get("ptr").(int64) == 10)
fmt.Println(doc.Get("ptr1").(int64) == 10)

ptr = nil

doc.Set("ptr1", ptr1)
// ptr1不为nil，但它指向nil的"ptr"指针，所以字段被设置为nil
fmt.Println(doc.Get("ptr1") == nil)

无效类型不会改变文档：

doc := c.NewDocument()
doc.Set("myField", make(chan struct{}))

log.Println(doc.Has("myField")) // 将输出false

贡献

CloverDB正在积极开发中。任何形式的贡献，无论是建议、错误报告还是拉取请求，都非常欢迎 :blush:

以下用户的贡献和建议已被感激地接受：

<a href="https://github.com/ostafen/clover/graphs/contributors"> <img src="https://contrib.rocks/image?repo=ostafen/clover" /> </a>

使用contrib.rocks制作。