ThingsDB can work with a single node but is designed to work with at least two nodes but three nodes are preferred. Running on three nodes brings redundancy and ensures the database stays operational, even while you for example upgrade ThingsDB to a newer version.
After building the source code and making a symlink, you can start your first node using the following command. You need to add the --init flag to initialize a new ThingsDB store.
thingsdb --init
Starting a second (or other) node needs a secret.
thingsdb --secret second
The secret is used when adding this node; see new_node documentation on how to add a second (or other) node to ThingsDB.
| Flag | Description |
|---|---|
-h, --help |
Show the help message and exit. |
-c, --config CONFIG |
Define which ThingsDB configuration file to use. |
--deploy |
Auto set --init or --secret based on the THINGSDB_NODE_NAME and THINGSDB_NODE_SECRET environment variable. A use case is explained in the next paragraph. |
--init |
Initialize a new ThingsDB store. |
--force |
Force --init or --secret to remove existing data if exists. |
--secret SECRET |
Set one time secret and wait for request to join. |
--rebuild |
Rebuild the node (can only be used when having >1 nodes). A use case is explained in the next paragraph. |
--forget-nodes |
Forget all nodes info and load ThingsDB with a single node. A use case is explained in the next paragraph. |
-v, --version |
Show version information and exit. |
-l, --log-level |
Set initial log level: debug, info, warning, error, critical. |
--log-colorized |
Use colorized logging. |
-y, --yes |
Confirm questions with yes. |
Arguments are not supported in all cases. If needed, --init, --secret and --deploy can be replaced with enviroment variable.
| Argument | Environment variable | Description |
|---|---|---|
--init |
THINGSDB_INIT |
Set to 1 to use --init, example: THINGSDB_INIT=1. |
--secret |
THINGSDB_SECRET |
Set some secret, example: THINGSDB_SECRET=pass. |
--deploy |
THINGSDB_DEPLOY |
Set to 1 to use --deploy, example: THINGSDB_DEPLOY=1. |
In containerized environments like kubernetes it is often useful to initialize automatically based on the node name.
The --deploy argument is created for this purpose and triggers the following behavior.
-0, the node is considered to be the first node and will automatically set
the --init argument in case the node is started for the first time.-0, then the node will be started with --secret when the node is started
for the first time. The secret will be equal to the node name unless the environment
variable THINGSDB_NODE_SECRET is set.When you need to restore from a back up you will need to set the environment variable THINGSDB_STORAGE_PATH to the latest backup file (.tar.gz). Then you can start ThingsDB again with the following command:
thingsdb --forget-nodes
The --forget-nodes flag is in this case very useful. The flag causes to forget all nodes. You can just start with one node without getting in a situation where the quorum will not be reached when multiple nodes are down. After the first node has started you can then simply add other nodes again.
When you get in the situation that one of your nodes is corrupted for some reason, you can shutdown the node and start it again with the following flag:
thingsdb --rebuild
This causes the node to wipe its corrupted data and synchronize again with one of the other healthy nodes.
Using the --rebuild flag is a simplified way of doing the following but same thing. You shutdown the corrupted node. Delete it as well, so the other nodes forget about this node. Then start the node again with the following command:
thingsdb --force
The --force flag causes to wipe all the stored data and start fresh. Then you can add this node again to the ThingsDB store.
As you will notice this takes a couple of more steps, so it is easier to just use the --rebuild flag.