Quick start with a local cluster

You will start a three-node cluster on your machine with a single command, write data to it and see its nodes and ranges with the same commands you would use against a cluster of three machines. It lets you develop against several nodes without preparing machines.

What you will get

Three nodes forming a cluster inside a single process, with the data in memory. It takes about five minutes.

Before you begin

You need the teseladb binary and mongosh. If you do not have the binary yet, follow Install on Linux.

Step 1. Start the three nodes

teseladb dev --nodes 3

Node k listens on the client port plus k, so the three serve on 27017, 27018 and 27019, always on 127.0.0.1. The command prints one ready line per node. Note the administration port the log records for each one, because you use it in step 3.

Step 2. Connect and write data

mongosh "mongodb://127.0.0.1:27017,127.0.0.1:27018,127.0.0.1:27019/"

db.orders.insertMany([
  { customer: "Ana", total: 30 },
  { customer: "Luis", total: 12 },
]);

Open another terminal and connect with the three nodes in the string; this development cluster uses neither TLS nor users, so the string carries no option. The answer to insertMany confirms the write and gives the _id of each document:

{
  acknowledged: true,
  insertedIds: {
...
  }
}

Step 3. Look at the nodes and the ranges

teseladb admin --node 127.0.0.1:<port> nodes
teseladb admin --node 127.0.0.1:<port> ranges --collection test.orders

Use as <port> the administration port of any of the three nodes. Both commands ask the same node, which answers for the whole cluster.

Check that it works

nodes lists the three nodes as active. ranges shows the ranges of the orders collection, with the replicas of each range and the node that leads it; with two documents there is only one range, which has a replica on each node.

Clean up

Stop the process with Ctrl+C. The data was in memory, so it goes away with the process and the next teseladb dev starts from an empty cluster.

Next steps

• Deploy with systemd, to set up the same cluster on three machines.
• Ranges and replicas, to understand what you saw in step 3.