Managing Clusters Using the C (libcouchbase) SDK with Couchbase Server
The primary means for managing clusters is through the Couchbase Web UI which provides an easy to use interface for adding, removing, monitoring and modfying buckets. In some instances you may wish to have a programmatic interface, for example if running as part of a setup script, or if setting up buckets for testing.
You may perform Couchbase management operations from any HTTP client (e.g. libcurl). The C SDk comes with an embedded HTTP client which may also be used to execute management operations. The SDK also provides high level management functions for dealing with N1QL indexes.
HTTP Client Overview
The HTTP client is used via the lcb_http3()
function.
This function takes an lcb_CMDHTTP
structure containing the endpoint to contact and any payload information.
The lcb_CMDHTTP::type
field should be set to the appropriate API type for the operation.
The types are:
-
LCB_HTTP_TYPE_VIEWS
for design document management -
LCB_HTTP_TYPE_MANAGEMENT
for adding/removing/modifying buckets
You should also set the URL path via LCB_CMD_SET_KEY
.
The path should be the full path to the API endpoint, but without the host and scheme.
Other important fields within the lcb_CMDHTTP
structure are:
-
username
,password
: The username and password to use for authorization. This may be left empty (in which case, the bucket credentials are used), or populated with the administrative credentials in the case of cluster management operations. -
method
: The HTTP method to use. This is represented by one of theLCB_HTTP_METHOD_*
constants, for exampleLCB_HTTP_METHOD_POST
orLCB_HTTP_METHOD_GET
. -
body
,nbody
: If the request requires a payload, it should be specified in these fields, which contain the body buffer and its size, respectively. -
content_type
: If using a request body, many Couchbase REST APIs will also require that theContent-Type
HTTP header be set. Be sure to set this to the appropriate value (usually"application/json"
).
// Install the callback..
lcb_install_callback3(instance, LCB_CALLBACK_HTTP, (lcb_RESPCALLBACK)http_callback);
// Create the required parameters according to the Couchbase REST API
std::string path("/pools/default/buckets");
std::string params;
params += "name=newBucket&";
params += "type=couchbase&";
// authType should always be SASL. You can leave the saslPassword field
// empty if you don't want to protect this bucket.
params += "authType=sasl&saslPassword=&";
params += "ramQuotaMB=256";
printf("Using %s\n", params.c_str());
lcb_CMDHTTP htcmd = { 0 };
LCB_CMD_SET_KEY(&htcmd, path.c_str(), path.size());
htcmd.body = params.c_str();
htcmd.nbody = params.size();
htcmd.content_type = "application/x-www-form-urlencoded";
htcmd.method = LCB_HTTP_METHOD_POST;
htcmd.type = LCB_HTTP_TYPE_MANAGEMENT;
htcmd.username = "Administrator";
htcmd.password = "123456";
lcb_http3(instance, NULL, &htcmd);
And in the callback:
static void
http_callback(lcb_t, int, const lcb_RESPHTTP *resp)
{
printf("Operation completed with HTTP code: %d\n", resp->htstatus);
printf("Payload: %.*s\n", (int)resp->nbody, resp->body);
}