diff --git a/README.md b/README.md index 7e82df71..4878a217 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,16 @@ [twitter-badge]: https://img.shields.io/twitter/follow/engulaio?style=flat-square&logo=twitter&color=brightgreen [twitter-url]: https://twitter.com/intent/follow?screen_name=engulaio -Engula is a distributed key-value store. +Engula is a distributed key-value store, used as a cache, database, and storage engine. + +## Architecture + +![topology][topology] + +See [design doc][design-doc] for more details. + +[topology]: ./docs/img/topology.drawio.svg +[design-doc]: ./docs/design.md ## Quick start @@ -30,15 +39,7 @@ bash scripts/bootstrap.sh setup cargo run -- shell ``` -Then types: - -``` -config create-if-missing true -config database db-name -config collection collection -put foo bar -get baz -``` +Run and enjoy it. ## Contributing @@ -46,4 +47,4 @@ Thanks for your help in improving the project! We have a [contributing guide](CO ## More information -Design documentation is still being written. For informal discussions, please go to the [forum](https://github.com/engula/engula/discussions). +For informal discussions, please go to the [forum](https://github.com/engula/engula/discussions). diff --git a/docs/design.md b/docs/design.md new file mode 100644 index 00000000..3c2c3485 --- /dev/null +++ b/docs/design.md @@ -0,0 +1,61 @@ +# Design + +## What is Engula? + +Engula is a distributed key-value store, used as a cache, database, and storage engine. + +It has the following advantages: + +- Elasticity + + engula supports automatic data migration and balancing, which allows you easily to scale up or down based on you application needs. + +- Fault tolerance + + engula replicates data to multiple machines, the raft consensus is employed to ensure consistency between replicas and provide automatically fault recovery. + +- Easy to use + + engula is architected and designed with ease of use in mind. In deployment, there is only one binary, the topology is simple, and other nodes such as proxy, master, etc. are not needed. In addition, engula automatically completes resource configuration as much as possible without requiring users to configure various parameters. + +## Architecture + +In order to reduce the complexity of deployment and operation and maintenance, all the functions of engula are concentrated on a binary. + +![topology][topology] + +[topology]: ./img/topology.drawio.svg + +As shown in the figure above, all nodes in a cluster are engula servers, which internally coordinate and elect nodes that serve metadata. + +In engula, a replication set is called a **Group**. A leader is elected within a Group to serve read and write requests targeting this Group. Groups can be migrated between servers to achieve load balancing. + +![architecture][architecture] + +[architecture]: ./img/architecture.drawio.svg + +Group 0 is called the **Root Group**, which is responsible for balancing, schema maintenance, and providing routing information. + +Apart from the root, the storage part of the engula server is called **Node**. Node is responsible for data access, log replication and shard migration. (A shard is the smallest granularity of data and will be introduced later.) + +In addition, node is also responsible for providing group-level scheduling, including automatic maintaining num of replicas, automatic replace bad replicas, and replica migration between servers. + +## Data organization + +![data organization][data-organization] + +[data-organization]: ./img/data-organization.drawio.svg + +Engula provides two levels of data organization: database and collection. + +Database is used to provide isolation between tenants; collection is used to provide data isolation within tenants. + +A collection is partitioned into **Shards** to support elastic scale up or down. Currently engula supports both range and hash partitions. Shard splitting and merging will be introduced in subsequent releases. + +Shards are managed by groups, and the replicas of group is also replicas of shards. + +![group and shard][group-and-shard] + +[group-and-shard]: ./img/group-and-shard.drawio.svg + +As shown in the figure above, a group may be responsible for managing multiple shards. Shards can also be migrated online between groups. diff --git a/docs/img/architecture.drawio.svg b/docs/img/architecture.drawio.svg new file mode 100644 index 00000000..3a806cc3 --- /dev/null +++ b/docs/img/architecture.drawio.svg @@ -0,0 +1,255 @@ + + + + + + + + + + +
+
+
+ Liveness +
+
+
+ + + Liveness + + + + + + + +
+
+
+ Balancer +
+
+
+ + + Balancer + + + + + + + +
+
+
+ Schema +
+
+
+ + + Schema + + + + + + + +
+
+
+ Allocator +
+
+
+ + + Allocator + + + + + + + +
+
+
+ Shard Migration +
+
+
+ + + Shard Migration + + + + + + + +
+
+
+ Replica +
+
+
+ + + Replica + + + + + + + +
+
+
+ Scheduler +
+
+
+ + + Scheduler + + + + + + + +
+
+
+ Root +
+
+
+ + + Root + + + + + + + +
+
+
+ Node +
+
+
+ + + Node + + + + + + + + +
+
+
+ Log +
+
+
+ + + Log + + + + + + + +
+
+
+ Snapshot +
+
+
+ + + Snapshot + + + + + + + +
+
+
+ Raft Group +
+
+
+ + + Raft Group + + + + + + + +
+
+
+ Transport +
+
+
+ + + Transport + + + + + + + +
+
+
+ Engine +
+
+
+ + + Engine + + + + + + + + + Viewer does not support full SVG 1.1 + + + + \ No newline at end of file diff --git a/docs/img/data-organization.drawio.svg b/docs/img/data-organization.drawio.svg new file mode 100644 index 00000000..02e98b09 --- /dev/null +++ b/docs/img/data-organization.drawio.svg @@ -0,0 +1,154 @@ + + + + + + + + +
+
+
+ Database 1 +
+
+
+ + + Database 1 + + + + + + + +
+
+
+ Database 2 +
+
+
+ + + Database 2 + + + + + + + +
+
+
+ Collection 1 +
+
+
+ + + Collection 1 + + + + + + + +
+
+
+ Colleciton 2 +
+
+
+ + + Colleciton 2 + + + + + + + +
+
+
+ Shard 1 +
+
+
+ + + Shard 1 + + + + + + + +
+
+
+ Shard 2 +
+
+
+ + + Shard 2 + + + + + + + +
+
+
+ Shard N +
+
+
+ + + Shard N + + + + + + + +
+
+
+ Colleciton X +
+
+
+ + + Colleciton X + + + + + + + + + + + + + Viewer does not support full SVG 1.1 + + + + \ No newline at end of file diff --git a/docs/img/group-and-shard.drawio.svg b/docs/img/group-and-shard.drawio.svg new file mode 100644 index 00000000..81cff0c7 --- /dev/null +++ b/docs/img/group-and-shard.drawio.svg @@ -0,0 +1,187 @@ + + + + + + + + + + +
+
+
+ S1 +
+
+
+ + + S1 + + + + + + + +
+
+
+ S2 +
+
+
+ + + S2 + + + + + + + + +
+
+
+ shard migration +
+
+
+ + + shard migration + + + + + + + +
+
+
+ S2 +
+
+
+ + + S2 + + + + + + + +
+
+
+ S2 +
+
+
+ + + S2 + + + + + + + +
+
+
+ S4 +
+
+
+ + + S4 + + + + + + + +
+
+
+ S5 +
+
+
+ + + S5 + + + + + + + +
+
+
+ Group 1 +
+
+
+ + + Group 1 + + + + + + + +
+
+
+ Group 2 +
+
+
+ + + Group 2 + + + + + + + +
+
+
+ S6 +
+
+
+ + + S6 + + + + + + + + + Viewer does not support full SVG 1.1 + + + + \ No newline at end of file diff --git a/docs/img/topology.drawio.svg b/docs/img/topology.drawio.svg new file mode 100644 index 00000000..d378adb7 --- /dev/null +++ b/docs/img/topology.drawio.svg @@ -0,0 +1,323 @@ + + + + + + + + + +
+
+
+ Group 0 +
+
+
+ + + Group 0 + + + + + + + +
+
+
+ Group 1 +
+
+
+ + + Group 1 + + + + + + + +
+
+
+ Group 2 +
+
+
+ + + Group 2 + + + + + + + + +
+
+
+ Group 0 +
+
+
+ + + Group 0 + + + + + + + +
+
+
+ Group 2 +
+
+
+ + + Group 2 + + + + + + + +
+
+
+ Group 3 +
+
+
+ + + Group 3 + + + + + + + + +
+
+
+ Group 0 +
+
+
+ + + Group 0 + + + + + + + +
+
+
+ Group 1 +
+
+
+ + + Group 1 + + + + + + + +
+
+
+ Group 3 +
+
+
+ + + Group 3 + + + + + + + + +
+
+
+ Group 1 +
+
+
+ + + Group 1 + + + + + + + +
+
+
+ Group 2 +
+
+
+ + + Group 2 + + + + + + + +
+
+
+ Group 3 +
+
+
+ + + Group 3 + + + + + + + +
+
+
+ Engula Client +
+
+
+ + + Engula Client + + + + + + + +
+
+
+ + + Engula Server + + +
+
+
+ + + Engula Se... + + + + + + + +
+
+
+ + + Engula Server + + +
+
+
+ + + Engula Se... + + + + + + + +
+
+
+ + + Engula Server + + +
+
+
+ + + Engula Se... + + + + + + + +
+
+
+ + + Engula Server + + +
+
+
+ + + Engula Se... + + + + + + + + + Viewer does not support full SVG 1.1 + + + + \ No newline at end of file