When you’re a Database or System Administrator, you don’t always have time to go through the setup wizards when deploying a new piece of software. Probably because you are managing massive amounts of systems in a large organization.
So what are you going to do when it comes to your distributed database cluster?
Couchbase Server comes with a RESTful API that is perfect for provisioning instances, whether that be creating new clusters or joining to existing clusters. We’re going to see how to use some of those API endpoints.
Installing Couchbase Server for Mac, Linux, or Windows
Regardless if you wish to configure Couchbase Server over HTTP or not, you’re still going to need to install the software first. There is a binary available for Mac, Linux, and Windows, all found in the download section of the Couchbase website.
If you’d prefer, you can also find various cloud images available for services like Amazon, Azure, and Docker.
Creating a New Cluster with the Command Line
Once Couchbase Server is installed and running, we can take advantage of the RESTful API endpoints to complete the configuration of the instance.
The first thing we want to do is define how much memory to allocate to our instance:
|
1 2 3 |
curl -v -X POST http://localhost:8091/pools/default -d memoryQuota=512 -d indexMemoryQuota=512 |
The above command will allocate the instance with 512MB of memory and 512MB of index memory. Of course both should be adjusted based on your needs.
We also need to define which services will be available on our instance:
|
1 2 |
curl -v http://localhost:8091/node/controller/setupServices -d services=kv%2cn1ql%2Cindex |
In the above we have a comma delimited list of services where the comma is URL-encoded to be %2C. The services in this example will be the key-value service (KV), the N1QL service, and the index service. Depending on your needs you may or may not want to enable all these services.
The Couchbase instance is very open and insecure as of right now because there is no administrative account created yet. It is a good idea to create that administrative account now:
|
1 2 3 4 |
curl -v http://localhost:8091/settings/web -d port=8091 -d username=Administrator -d password=password |
In the above example we are defining the administrative username to be Administrator and the password to be password. Probably not a good choice in a production environment.
Out of the box we have no buckets in our Couchbase instance, so we should probably go ahead and create one. From the command line, execute:
|
1 2 3 4 5 6 |
curl -v -u Administrator:password -X POST http://localhost:8091/pools/default/buckets -d name=example -d bucketType=couchbase -d ramQuotaMB=256 -d authType=sasl |
The above bucket creation command is doing quite a bit. We’re providing the administrative information to the instance in our request. The bucket we’re creating will be named example and it will be a couchbase bucket type. There are a few bucket types you can choose from, so don’t think we only have one option. The memory allocation of this bucket will be 256MB of the 512MB that we gave to this server.
Finally, since we are using N1QL, it might make sense to create a primary index on the bucket. Go ahead and execute the following:
|
1 2 |
curl -v http://localhost:8093/query/service -d 'statement=create primary index on example' |
At this point, the new instance should be fully functional. You should note that the RESTful API offers so much more in terms of configuration than what we explored and it is a good idea to check out what it has to offer.
Joining a Cluster with the Command Line
So what if we are spinning up nodes to be added to an already existing cluster? We can use the RESTful API to help us out.
From the command line, execute the following:
|
1 2 3 4 5 |
curl -u Administrator:password -d clusterMemberHostIp=10.0.1.99 -d clusterMemberPort=8091 -d user=Administrator -d password=password -d services=kv%2cn1ql%2cindex http://localhost:8091/node/controller/doJoinCluster |
The above command will take our node on localhost, or wherever our new node is located and join it to a cluster based on the clusterMemberHostIp. This new node will have all the same services, even though it is not a requirement that all nodes match.
Any time you add or remove nodes from a cluster, you’re going to want to rebalance that cluster. This can be accomplished with the following:
|
1 2 3 |
curl -v -X POST -u [admin]:[password] http://localhost:8091/controller/rebalance |
The rebalance process can take time depending on how much data you have.
Conclusion
You just saw how to configure a Couchbase Server cluster with the command line and the RESTful API endpoints. This is useful if you manage many servers and want to accomplish all this via a script. There are plenty of other scenarios where this would be useful as well. Maybe you have created a continuous deployment pipeline and need the database to be included in it.
There are many more API endpoints available and I strongly encourage you to check out the documentation regarding them.
English