https://github.com/auula/wiredb
WireDB is a NoSQL database based on Log-structured file system.
https://github.com/auula/wiredb
bitcask database kv kvdb kvstore log log-structuredfs nosql nosql-database restful-api storage storage-engine storage-provider
Last synced: about 2 months ago
JSON representation
WireDB is a NoSQL database based on Log-structured file system.
- Host: GitHub
- URL: https://github.com/auula/wiredb
- Owner: auula
- License: other
- Created: 2022-01-16T09:29:22.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2025-03-04T15:36:10.000Z (3 months ago)
- Last Synced: 2025-03-04T15:39:03.698Z (3 months ago)
- Topics: bitcask, database, kv, kvdb, kvstore, log, log-structuredfs, nosql, nosql-database, restful-api, storage, storage-engine, storage-provider
- Language: Go
- Homepage:
- Size: 3.47 MB
- Stars: 262
- Watchers: 4
- Forks: 32
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
WireDB is a NoSQL that supports multiple data types based on Log-structured file system.
---
[](https://img.shields.io/badge/go%20report-A+-brightgreen.svg?style=flat)
[](https://pkg.go.dev/github.com/auula/wiredb)
[](https://app.codacy.com/gh/auula/wiredb/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
[](https://codecov.io/gh/auula/wiredb)
[](https://app.deepsource.com/gh/auula/wiredb/?ref=repository-badge)
[](https://opensource.org/licenses/Apache-2.0)
[](https://github.com/auula/wiredb/releases)
---
[简体中文](README.md) | [English](README_EN.md)
---
## 🎉 Feature
- 支持多种内置的数据结构
- 高吞吐量、低延迟、高效批量数据写入
- 支持磁盘数据存储和磁盘垃圾数据回收
- 支持磁盘数据静态加密和静态数据压缩
- 支持 IP 白名单功能保障数据的安全访问
- 支持通过基于 RESTful API 协议操作数据
---
## 🚀 Quick Start
使用 Docker 可以快速部署 [`wiredb:latest`](https://hub.docker.com/r/auula/wiredb) 的镜像来测试 WireDB 提供的服务，运行以下命令即可拉取 WireDB 镜像：
```bash
docker pull auula/wiredb:latest
```
运行 WireDB 镜像启动容器服务，并且映射端口到外部主机网络，执行下面的命令：
```bash
docker run -p 2668:2668 auula/wiredb:latest
```
WireDB 提供使用 RESTful API 的方式进行数据交互，理论上任意具备 HTTP 协议的客户端都支持访问和操作 WireDB 服务实例。在调用 RESTful API 时需要在请求头中添加 `Auth-Token` 进行鉴权，该密钥由 WireDB 进程自动生成，可通过容器运行时日志获取，使用以下命令查看启动日志：
```bash
root@2c2m:~# docker logs 66ae91bc73a6
_ ____
_ __(_)______ ___/ / /
| |/|/ / / __/ -_) _ / _ \
|__,__/_/_/ \__/\_,_/_.__/ v1.1.2
WireDB is a NoSQL database based on Log-structured file system.
Software License: Apache 2.0 Website: https://wiredb.github.io
[WIREDB:C] 2025/02/27 10:07:01 [WARN] The default password is: T9EHAvi5dcIpPK9G#ADlVj4NB 👈
[WIREDB:C] 2025/02/27 10:07:01 [INFO] Logging output initialized successfully
[WIREDB:C] 2025/02/27 10:07:01 [INFO] Loading and parsing region data files...
[WIREDB:C] 2025/02/27 10:07:01 [INFO] Region compression activated successfully
[WIREDB:C] 2025/02/27 10:07:01 [INFO] File system setup completed successfully
[WIREDB:C] 2025/02/27 10:07:01 [INFO] HTTP server started at http://172.0.0.1:2668 🚀
```
如果计划将 WireDB 作为长期运行的服务，推荐直接使用主流 Linux 发行版来运行而非容器技术。采用裸机 Linux 部署 WireDB 服务，可手动优化存储引擎参数，以获得更稳定的性能和更高的资源利用率，具体参数配置建议查看[官方文档](https://docs.wiredb.org)。
---
## 🕹️ RESTful API
目前 WireDB 服务对外提供数据交互接口是基于 HTTP 协议的 RESTful API ，只需要通过支持 `HTTP` 协议客户端软件就可以进行数据操作。这里推荐使用 `curl` 软件进行数据交互操作，WireDB 内部提供了多种数据结构抽象，例如 Table 、List 、ZSet 、Set 、Number 、Text 类型，这些数据类型对应着常见的业务代码所需使用的数据结构，这里以 Table 类型结构为例进行 RESTful API 数据交互的演示。
Table 结构类似于 JSON 及任何有映射关系的半结构化数据，例如编程语言中的 struct 和 class 字段都可以使用 Table 进行存储，下面是一个 Table 结构 JSON 抽象，其中的 `ttl` 字段为设置存活时间，超过 120 秒后会被主动删除：
```json
{
"table": {
"is_valid": false,
"items": [
{
"id": 1,
"name": "Item 1"
},
{
"id": 2,
"name": "Item 2"
}
],
"meta": {
"version": "2.0",
"author": "Leon Ding"
}
},
"ttl": 120
}
```
下面是 curl 进行数据存储操作的例子，由于是 RESTful API 设计风格，需要在 HTTP 的请求路径 URL 加上数据类型信息。注意存储使用 HTTP 协议的 PUT 方法进行操作，使用 PUT 方法会直接创建新数据版本覆盖掉旧的数据版本，命令如下：
```bash
curl -X PUT http://localhost:2668/table/key-01 -v \
-H "Content-Type: application/json" \
-H "Auth-Token: T9EHAvi5dcIpPK9G#ADlVj4NB" \
--data @tests/table.json
```
获取数据的方式只需要将 HTTP 的请求改为 GET 方式就会获取得 Key 相应的存储记录，命令如下：
```bash
curl -X GET http://localhost:2668/table/key-01 -v \
-H "Auth-Token: T9EHAvi5dcIpPK9G#ADlVj4NB"
```
删除对应的数据记录，只需要将 HTTP 的请求改为 DELETE 的方式即可，命令如下：
```bash
curl -X DELETE http://localhost:2668/table/key-01 -v \
-H "Auth-Token: T9EHAvi5dcIpPK9G#ADlVj4NB"
```
更为复杂的查询和复杂更新操作，将在后续的版本更新中添加支持。其他数据结构类型操作代码示例请查看[官方文档](https://docs.wiredb.org)。
---
## 🧪 Benchmark Test
由于底层存储引擎是以 Append-Only Log 的方式将所有的操作写入到数据文件中，所以这里给出的测试用例报告，是针对的其核心文件系统 [`vfs`](./vfs/) 包的写入性能测试的结果。运行测试代码的硬件设备配置信息为（Intel i5-7360U, 8GB LPDDR3 RAM），写入基准测试结果如下：
```bash
$: go test -benchmem -run=^$ -bench ^BenchmarkVFSWrite$ github.com/auula/wiredb/vfs
goos: darwin
goarch: amd64
pkg: github.com/auula/wiredb/vfs
cpu: Intel(R) Core(TM) i5-7360U CPU @ 2.30GHz
BenchmarkVFSWrite-4 173533 7283 ns/op 774 B/op 20 allocs/op
PASS
ok github.com/auula/wiredb/vfs 2.806s
```
在项目根目录下有一个 [`tools.sh`](./tools.sh) 的工具脚本文件，可以快速帮助完成各项辅助工作。
---
## 🌟 Stargazers over time
[](https://starchart.cc/wiredb/wiredb)
---
## 👬 Contributors
🤝 Thanks to all the contributors below!
