About These Docs
Meta documentation — what you might need to know to get the best from these docs, from their intent to their Information Architecture.
Welcome to the C++ SDK 1.0 docs — this is an afterword to the documentation, rather than something most people will read as a foreword. Why so? On most occasions you will arrive at a page directly from a search engine or LLM, perhaps follow a link to another page or two, and then depart (with, we hope, your questions answererd). This page is to help with those occasions when you are unsure precisely what you want, but you are after understanding — so this page is a guide to the SDK docs, to help you to get the most from them.
Assumptions & Presumptions
Couchbase is a complex and powerful product, with many components. The SDKs interact with Couchbase Server and its various services; although some links are given to the pages for these services, gaining an understanding of them is not the principal aim of the SDK documentation, rather it is to gain an understanding of how to interact with them programmatically from the SDK, as many application programmers will have the task specced out for them.
Some concepts, such as Role-Based Access Control, do need to be understood in greater depth — but this is documented in the appropriate place in the Server docs, and the Capella docs, and linked from the Getting Started Guide. Additionally, things which are essential in production can be a barrier to getting up and running quickly in order to try something out — so the Full Admin RBAC role is used in the Hello World code example, contrary to best practice (but this is, of course, called out).
Concepts, Howtos, and Reference Information
Earlier SDK docs led with sections of Howto guides, with reference and discussion (concept) docs appended to the end along with project docs such as release notes. Whilst howtos, with their easily parseable code snippets, are what the majority of developers want most of the time, a broader context is often needed go ensure that any SDK API is used appropriately.
Furthermore, for developers with less experience of databases in the distributed world, some discussion of the issues of consistency and isolation can ensure that the right decisions are made once your app use starts to scale up. Hence each section carries a broad introduction, highlighting points to consider, but skippable by those who already know the territory.
Limits of the SDK Docs
Large as this docset is, it can only cover a subset of the complette SDK API. For a comprehensive answer to anything not completely covered in these docs, your first port of call should always be the API reference. For many languages, you will also access this from your chosen IDE.
Getting Started
The Getting Started section contains tutorial pages — in intention, if not always in style — covering how to install and start using the SDK, as well as a longer Sample Application (which is not present for every SDK).
It also contains information on connecting to the database, and a section of troubleshooting information for when the application code is remote from the database — such as developing an app on your laptop, with the Cluster in the Cloud Service Provider’s Zone some distance away — a set-up not supported in production, but typical in development or evaluation.
Data Modelling, Durability, and Consistency
A database has a simple job — storing your data, and giving some of it back to you when you ask. Behind that simplicity is a whole world of difficulty, to ensure the best combination of consistency and availability of documents partitioned across many nodes. Our introduction suggests key areas to consider when scaling up your app.
This section also contains details of interacting with our super fast Data Service, bandwidth-saving Sub-Document APIs, and compression, Field-Level Encryption, and working with non-JSON data.
Querying Your Data
For developers with an RDBMS, Couchbase’s SQL implementation, SQL++, makes querying familiar. But don’t be so quick to jump straight to SQL++ — assess your use case carefully.
In addition to SQL++ queries, and longer running analytics queries (OLAP) queries, and a Search Service (which includes Vector Search), you can quickly access data where you know keys or key ranges, and this can be substantially quicker, thanks to the Data Service’s speedy binary protocol.
Distributed ACID Transactions
As with SQL++ queries, ACID transactions may be a familiar tool that you choose automatically — but take time to weigh up your use case against the constraints of such a consistency model.
Dealing with Delays, Outages, and Unreliable Networks
A distributed world brings challenges not just of node and network failures, but even of operating with uncertain knowledge of those things. Couchbase is architected to give reliable results but as always, taking time to understand the issue can give you a more reliable application, and a better service to your users.
This section also contains details of the observability stack available within the SDK, to help to identify problems and profile bottlenecks.
Best Practices
Choice is the mantra of many programming languages, and Couchbase offers support for many approaches to programming and architectural choices. Where possible, we offer strong recommendations, for what will work best in most circumstances.
This section also contains discussions for some of the best ways of dealing with errors and exceptions.
Managing Couchbase
Some will prefer to administer Couchbase programmatically, rather than through UI, REST API, or command line. This section covers the available management APIs in the SDK.
SDK Deployment
A section on those non-programmatic considerations — compatibility guides, migration, third party integrations, licensing, and release notes.
Reference Docs
The key reference doc is the API guide, which should be an accurate and complete source of truth for programming with the C++ SDK’s API. Any error here should be filed directly against the individual SDKs bug tracker (JIRA), although a ticket against the docs here will always be converted to the correct project.
The first link in the navigation for the Reference Section is to the API Guide for the latest version of the SDK. Links to previous versions can be found with the Release Notes.
Other reference material includes the Client Settings that can be adjusted, and a listing of all Error Codes.
Another Route Through?
Each page contains several links to related pages in the docs, as well as to relevant sections of the latest generated API docs. Links are made to cover as many common user journeys as we could think of. For cases where we didn’t anticipate your needs, every page in each SDK is linked from the left-hand navigation, and the paragraphs above detail the broad purpose of these groupings and some of their content.
Older SDK Versions
All supported versions of the SDKs can be found in the doc set — use the dropdown version selector in the left-hand navigation to reach each one. Documentation on older, unsupported versions of the SDK — that have reached end-of-life — can be found in the archive.