From deccba34062025b71c1aba3c51faccd5a08cd932 Mon Sep 17 00:00:00 2001
From: k32 <10274441+k32@users.noreply.github.com>
Date: Wed, 27 Oct 2021 09:27:25 +0200
Subject: [PATCH] fix(schema): Improve configuration of the internal DB

---
 apps/emqx_conf/etc/emqx_conf.conf       | 28 ++++++++--
 apps/emqx_conf/src/emqx_conf_schema.erl | 68 ++++++++++++++++---------
 2 files changed, 68 insertions(+), 28 deletions(-)

diff --git a/apps/emqx_conf/etc/emqx_conf.conf b/apps/emqx_conf/etc/emqx_conf.conf
index fcb7a2947..e57bc4869 100644
--- a/apps/emqx_conf/etc/emqx_conf.conf
+++ b/apps/emqx_conf/etc/emqx_conf.conf
@@ -306,14 +306,32 @@ cluster {
     ## Default: default
     namespace = default
   }
+}
 
-  db_backend = mnesia
+##==================================================================
+## Internal database
+##==================================================================
+db {
+  ## Database backend
+  ##
+  ## @doc db.backend
+  ## ValueType: mnesia | rlog
+  ## Default: mnesia
+  backend = mnesia
 
-  rlog {
-      # role: core
-      # core_nodes: []
-  }
+  ## RLOG role
+  ##
+  ## @doc db.role
+  ## ValueType: core | replicant
+  ## Default: core
+  role = core
 
+  ## Replicant core nodes
+  ##
+  ## @doc db.core_nodes
+  ## ValueType: comma-separated node list
+  ## Default: ""
+  core_nodes = ""
 }
 
 ##==================================================================
diff --git a/apps/emqx_conf/src/emqx_conf_schema.erl b/apps/emqx_conf/src/emqx_conf_schema.erl
index ba3ac31b6..cfcc12905 100644
--- a/apps/emqx_conf/src/emqx_conf_schema.erl
+++ b/apps/emqx_conf/src/emqx_conf_schema.erl
@@ -72,8 +72,7 @@ roots() ->
        sc(hoconsc:ref("cluster"),
           #{ desc => "EMQ X nodes can form a cluster to scale up the total capacity.<br>"
                      "Here holds the configs to instruct how individual nodes "
-                     "can discover each other, also the database replication "
-                     "role of this node etc."
+                     "can discover each other."
            })}
     , {"log",
        sc(hoconsc:ref("log"),
@@ -101,6 +100,10 @@ natively in the EMQ X node;<br>
 'postgresql' etc. to look up clients or rules from external databases;<br>
 """
            })}
+    , {"db",
+       sc(ref("db"),
+          #{ desc => "Settings of the embedded database."
+           })}
     ] ++
     emqx_schema:roots(medium) ++
     emqx_schema:roots(low) ++
@@ -146,14 +149,6 @@ fields("cluster") ->
     , {"k8s",
        sc(ref(cluster_k8s),
           #{})}
-    , {"db_backend",
-        sc(hoconsc:enum([mnesia, rlog]),
-          #{ mapping => "mria.db_backend"
-           , default => mnesia
-           })}
-    , {"rlog",
-       sc(ref("rlog"),
-          #{})}
     ];
 
 fields(cluster_static) ->
@@ -251,19 +246,6 @@ fields(cluster_k8s) ->
            })}
     ];
 
-fields("rlog") ->
-    [ {"role",
-       sc(hoconsc:enum([core, replicant]),
-          #{ mapping => "mria.node_role"
-           , default => core
-           })}
-    , {"core_nodes",
-       sc(emqx_schema:comma_separated_atoms(),
-          #{ mapping => "mria.core_nodes"
-           , default => []
-           })}
-    ];
-
 fields("node") ->
     [ {"name",
        sc(string(),
@@ -328,6 +310,46 @@ fields("node") ->
         )}
     ];
 
+fields("db") ->
+    [ {"backend",
+       sc(hoconsc:enum([mnesia, rlog]),
+          #{ mapping => "mria.db_backend"
+           , default => mnesia
+           , desc => """
+Select the backend for the embedded database.<br/>
+<strong>Important!</strong> This setting should be the same on all nodes in the cluster.<br/>
+<strong>Important!</strong> Changing this setting in the runtime is not allowed.<br/>
+<code>mnesia</code> is the default backend, that offers decent performance in small clusters.<br/>
+<code>rlog</code> is a new experimantal backend that is suitable for very large clusters.
+"""
+           })}
+    , {"role",
+       sc(hoconsc:enum([core, replicant]),
+          #{ mapping => "mria.node_role"
+           , default => core
+           , desc => """
+Select a node role.<br/>
+<code>core</code> nodes provide durability of the data, and take care of writes.
+It is recommended to place core nodes in different racks or different availability zones.<br/>
+<code>replicant</code> nodes are ephemeral worker nodes. Removing them from the cluster
+doesn't affect database redundancy<br/>
+It is recommended to have more replicant nodes than core nodes.<br/>
+Note: this parameter only takes effect when the <code>backend</code> is set
+to <code>rlog</code>.
+"""
+           })}
+    , {"core_nodes",
+       sc(emqx_schema:comma_separated_atoms(),
+          #{ mapping => "mria.core_nodes"
+           , default => []
+           , desc => """
+List of core nodes that the replicant will connect to.<br/>
+Note: this parameter only takes effect when the <code>backend</code> is set
+to <code>rlog</code> and the <code>role</code> is set to <code>replicant</code>.
+"""
+           })}
+    ];
+
 fields("cluster_call") ->
     [ {"retry_interval",
        sc(emqx_schema:duration(),