1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
|
<h1>
<img src="./docs/imgs/swarmkv_logo.svg" align="left" height="40px" alt="swarmkv logo"/>
<span>SwarmKV</span>
</h1>
**SwarmKV is an embedded and distributed key-CRDT store with peer-to-peer networking for sharing memory by communicating.**
Main Features
- Cluster
- State-based CRDT syncronization
- Strong Eventual Consistency (in the language of [CAP](https://en.wikipedia.org/wiki/CAP_theorem), this system prioritizes availability and partition tolerance).
**Why not Redis?** Because SwarmKV is
- Embedded, **no** additional servers.
- [CRDT](https://en.wikipedia.org/wiki/Conflict-free_replicated_data_type) native
- Scalable for trillions of operations per second, billions of keys, and thousands of parallel operators
**Why not SQLite, rqlite, or dqlite?** Because Swarm KV is not designed to be a relational database and extremely fast.
<img src="./docs/imgs/cluster.png" alt="swamrkv-cluster" />
SwarmKV Data Types
- [String and Integer](./docs/commands/string_and_integer.md) by Last-Write-Wins (LWW) Register and Positive-Negative Counter.
- [Set](./docs/commands/set.md) by Observed-Remove Set (OR-Set).
- [Hash](./docs/commands/hash.md) embed string and integer by OR-Set.
- [Token Buckets](./docs/commands/token_bucket.md)
- Generic Token Buckets
- Fair Token Bucket: Implements weighted stochastic fairness allocation to ensure equitable resource distribution.
- Bulk Token Bucket: Optimized for scenarios requiring a large number of token buckets with identical configurations.
- [Bloom Filter](./docs/commands/bloom_filter.md) by age-partitioned bloom filter with the ability to expire.
- [Count-Min Sketch](./docs/commands/count_min_sketch.md).
- [HyperLogLog](./docs/commands/hyperloglog.md) by staggered HyperLogLog with the ability to expire.
- [Spread Sketch](./docs/commands/spread_sketch.md) by Spread Sketch with the ability to expire.
# Getting started
## Building SwarmKV
Download and unzip swarmkv-xx.zip
- Build swarmkv from source code (requires cmake version > 3.5)
- `mkdir swarmkv-xxx/build`
- `cd swarmkv-xxx/build`
- `cmake .. -DCMAKE_BUILD_TYPE=Debug`
- `make`
## Run Hashicorp Consul
SwarmKV uses [HashiCorp Consul](https://www.consul.io/) for cluster management, which includes leader election, health checking, and slot table management. You can download Hashicorp Consul from https://developer.hashicorp.com/consul/downloads.
Then, run consul agent in debug mode. If you are not familiar with Consul, there is a consul configuration file in swarmkv source directory, copy it to somewhere you desire.
- Edit `./swarmkv/test/consul.d/server.hcl` and set the `bind_addr ` as you need
- `./consul agent -dev -config-dir=./swarmkv/test/consul.d/`
Check consul UI via http://localhost:8500/ui
## Create Cluster
Create swarmkv cluster with `swarmkv-xxx/build/tools/swarmkv-cli`
```
[zhengchao@centos7-vm-dev tools]$ ./swarmkv-cli --cluster-create swarmkv-basic-test 127.0.0.1:5210
consul KV init slot table http://127.0.0.1:8500/v1/kv/swarmkv/swarmkv-basic-test/slots.
OK
[zhengchao@centos7-vm-dev tools]$ ./swarmkv-cli --cluster-create swarmkv-2-nodes 127.0.0.1:5210 127.0.0.1:5220
consul KV init slot table http://127.0.0.1:8500/v1/kv/swarmkv/swarmkv-2-nodes/slots.
OK
```
## Run test cases
```shell
cd test/
./swarmkv_gtest
```
## Playing with `swarmkv-cli`
```shell
[zhengchao@centos7-vm-dev tools]$ ./swarmkv-cli -n swarmkv-2-nodes
swarmkv-2-nodes> get id001
"lisi"
swarmkv-2-nodes> expire id001 60
(integer) 1
swarmkv-2-nodes>
```
## C API
The following example is two nodes (db[0] and db[1]) communicating via SwarmKV.
```c
#include "swarmkv/swarmkv.h"
#include "stdio.h"
#include "stdlib.h"
int main(int argc, char **argv)
{
struct swarmkv_options *opts[2];
struct swarmkv *db[2];
char *err=NULL;
const char *cluster_name="simple-example";
for(size_t i=0; i<2; i++)
{
opts[i]=swarmkv_options_new();
swarmkv_options_set_cluster_port(opts[i], 5210+i);
db[i]=swarmkv_open(opts[i], cluster_name, &err);
if(err)
{
printf("swarmkv_open failed: %s.\n", err);
free(err);
return -1;
}
}
const char *key="name";
const char *value="zhangsan";
struct swarmkv_reply *reply=NULL;
reply=swarmkv_command(db[0], "set %s %s", key, value);
swarmkv_reply_free(reply);
reply=swarmkv_command(db[1], "get %s", key);
if(reply->type==SWARMKV_REPLY_STRING)
{
printf("get name: %s\n", reply->str);
}
else
{
printf("get name failed, reply type: %d, str: %s\n",
reply->type, reply->str);
}
swarmkv_reply_free(reply);
for(size_t i=0; i<2; i++)
{
swarmkv_close(db[i]);
}
return 0;
}
```
It's recommended to use [jemalloc](https://github.com/jemalloc/jemalloc) for better performance.
# Further documentation
Here are some specific details about the SwarmKV.
* [Design](./docs/design.md)
* [Command-line interface (CLI)](./docs/cli.md)
* [Conflict-free Replicated Data Type (CRDT)](./docs/crdt.md)
* [Commands](./docs/command_toc.md)
|
