Hello World
Install, connect, try. A quick start guide to get you up and running with Couchbase and the C++ SDK.
Couchbase has a simple interface for creating and modifying records in a document, based upon the collection into which the documents are organized. You can read more about data modeling below, but first let’s look at those data operations, and installing the C++ SDK.
upsert()
auto collection = cluster.bucket(bucket_name).scope(scope_name).collection(collection_name);
const std::string document_id{ "minimal_example" };
const tao::json::value basic_doc{
{ "a", 1.0 },
{ "b", 2.0 },
};
auto [err, res] = collection.upsert(document_id, basic_doc, {}).get();
if (err) {
fmt::println("Unable to perform upsert: {}", err);
} else {
fmt::println("id: {}, CAS: {}", document_id, res.cas().value());
}
upsert
inserts (creates) the document if it does not exist, or replaces it if it does.
We’ll explore creating and retrieving data records in more detail below,
after walking through a quick installation.
Before You Start
Couchbase Capella, our Database-as-a-Service, lets you get on with what matters, while we take care of the administration for you. Alternately, if you need to control every aspect of deployment — or just want to run the Server in a VM on your laptop — there are several self-managed options available:
-
Couchbase Capella
-
Self-Managed Couchbase Server
If you haven’t already got a cluster set up, the easiest route is to sign up to a trial of Couchbase Capella, then come back to this page. Make a note of the endpoint to connect to, and remember the credentials for the user that you set up.
Install Couchbase Server locally, or in your private Cloud:
For the example code below to run, you’ll need the username and password of the Administrator user that you create, and the IP address of at least one of the nodes of the cluster.
Prerequisites
Check that you have the dependencies installed:
-
C++ 17 compiler
-
CMake version 3.19 or newer
Supprted Operating Systems are listed on the compatibility page.
The code examples also assume:
-
Couchbase Capella
-
Self-Managed Couchbase Server
-
You have signed up to Couchbase Capella.
-
You have created your own bucket, or loaded the Travel Sample dataset. Note, the Travel Sample dataset is installed automatically by the Capella free trial.
-
A user is created with permissions to access the cluster (at least Application Access permissions). See the Capella connection page for more details.
Couchbase Capella uses Roles to control user access to cluster resources. For the purposes of this guide, you can use the Organization Owner role automatically assigned to your account during installation of the Capella cluster. In production, Couchbase strongly recommends setting up users with more granular access roles as a best practice for data security. |
-
Couchbase Server is installed and accessible locally.
-
You have created your own bucket, or loaded the Travel Sample dataset using the Web interface.
-
A user is created with permissions to access your cluster (at least Application Access permissions). See Manage Users, Groups and Roles for more details.
Couchbase Server uses Role-Based Access Control (RBAC) to control access to cluster resources. In this guide we suggest using the Full Admin role created during setup of your local Couchbase Server cluster. In production, Couchbase strongly recommends setting up users with more granular access roles as a best practice for data security. |
Installation
More details of the installation process are in the full installation guide.
CPM.cmake is the recommended way to include the library in your project.
You need to include the following command in your CMakeLists.txt
.
CPMAddPackage(
NAME
couchbase_cxx_client
GIT_TAG
1.0.1
VERSION
1.0.1
GITHUB_REPOSITORY
"couchbase/couchbase-cxx-client"
OPTIONS
"COUCHBASE_CXX_CLIENT_STATIC_BORINGSSL ON")
IDE Plugins
To make development easier, Couchbase plugins are available for VSCode and the IntelliJ family of IDEs and editors. For links and more information on these and other integrations across the C++ ecosystem, check out the Integrations & Ecosystem page.
Connect to your Database
Connect to your Couchbase Capella operational cluster (or your local Couchbase Cluster, if you are trying out self-managed Couchbase).
-
Couchbase Capella
-
Self-Managed Couchbase Server
auto options = couchbase::cluster_options(username, password);
options.apply_profile("wan_development");
auto [err, cluster] = couchbase::cluster::connect(connection_string, options).get();
if (err) {
fmt::println("Unable to connect to the cluster: {}", err);
} else {
// Application code here
}
Note, the client certificate for connecting to a Capella cluster is included in the SDK installation.
couchbase::cluster_options options(username, password);
auto [err, cluster] = couchbase::cluster::connect(connection_string, options).get();
if (err) {
fmt::println("Unable to connect to the cluster: {}", err);
} else {
// Application code here
}
For a deeper look at connection options, read Managing Connections.
The connection code for getting started uses the Administrator password that you were given during set up. In any production app you should create a role restricted to the permissions needed for your app — more on this in the Security documentation. |
Create, Read, Update, Delete
Couchbase documents are organized into buckets, scopes, and collections. CRUD operations — Create, Read, Update, Delete — can be performed upon documents in a collection.
Insert (Create) and Upsert
insert
and upsert
will both create a new document.
The difference between the two is that if a document with that key already exists, the insert
operation will fail,
returning a document_exists
error — while the upsert
operation will succeed, replacing the content.
Get (Read)
The get
method reads a document from a collection.
If the collection does not have a document with this ID, the get
method also returns a document_not_found
error.
const std::string document_id{ "minimal_example" };
auto collection = cluster.bucket(bucket_name).scope(scope_name).collection(collection_name);
auto [err, res] = collection.get(document_id).get();
if (err) {
fmt::println("Unable to perform get: {}", err);
} else {
std::cout << "id: " << document_id << ", result: " << res.content_as<tao::json::value>() << "\n";
}
Replace (Update) and Overloads
auto collection = cluster.bucket(bucket_name).scope(scope_name).collection(collection_name);
const std::string document_id{ "minimal_example" };
const tao::json::value basic_doc{
{ "a", 1.0 },
{ "b", 2.0 },
};
auto [err, res] = collection.replace(document_id, basic_doc).get();
if (err) {
fmt::println("Unable to perform replace: {}", err);
} else {
fmt::println("id: {}, CAS: {}", document_id, res.cas().value());
}
When you replace a document, it’s usually good practice to use optimistic locking. Otherwise, changes might get lost if two people change the same document at the same time. |
Remove (Delete)
The remove method deletes a document from a collection:
auto collection = cluster.bucket(bucket_name).scope(scope_name).collection(collection_name);
const std::string document_id{ "minimal_example" };
auto [err, res] = collection.remove(document_id).get();
if (err) {
fmt::println("Unable to perform remove: {}", err);
} else {
fmt::println("id: {}, CAS: {}", document_id, res.cas().value());
}
Data Modeling
Documents are organized into collections — collections of documents that belong together. You get to decide what it means to "belong." Developers usually put documents of the same type in the same collection.
For example, imagine you have two types of documents: customers and invoices.
You could put the customer documents in a collection called customers
, and the invoice documents in a collection called invoices
.
Each document belongs to exactly one collection. A document’s ID is unique within the collection.
Different scopes can hold collections with different names. There is no relationship between collections in different scopes. Each collection belongs to just one scope and a collection’s name is unique within the scope.
More details can be found on the Data Model page.
What Next?
Next Steps
-
Discover SQL++ — our SQL-family querying language.
-
Explore some of the third party integrations with Couchbase and the C++ SDK, across the C++ ecosystem.