Introduction to Couchbase Capella Cloud with C#

This article was published as part of the C# Advent 2023, you can check out the rest of the articles here.

Couchbase is a distributed JSON database that comes with features found both in a NoSQL database and in a traditional RDMS. It specializes in low latency, high throughput reads and writes and comes with several other development friendly features such as a SQL query language, Free Text Search and Analytics services and others. Traditionally deployed on-premise, there is now a cloud-based DBaaS offering called Couchbase Capella which makes the entry into Couchbase seamless. In this post, I will discuss some topics regarding developing applications using Couchbase Capella and discuss some of the differences between developing with the on-premise version versus the cloud version of Couchbase.

Step 1: Getting Started

As of the writing of this blog, there is a free one-month trial of Couchbase Capella which I will use in the examples. To get started on this free tier, you can create an account for yourself on the Couchbase website.

Once you have the account setup, you’ll need to log into the console and then we will set up a Database, load a sample bucket and then get the connection string and configure the credentials. This will allow us to connect to Couchbase Capella from your application.

First we will set up the project that will contain our Database and Bucket.

Select the “Projects” tab and the click “Create Bucket” and finally add the name of your project to the text block and click “Create Project” again and the project will be created.

Next we will add the Database to the project.

Select the “Databases” tab and then the “Create Database” icon to start the process. A much larger dialogue page will open up allowing you to configure your database. I suggest for simplicity sake, you keep the defaults and just change the auto-generated database name to your choosing.

The default options will get you up and running on a Basic Plan (free 30-day trial) of a 3 node cluster, with 4 CPUs, 50GB storage configured with the Data, Query, Index and Search services pre-configured and running on AWS in the US East (N. Virginia) Availability Region.

Click the “Create Database” icon to allow Capella to build out the cluster and Database.

Note that while Capella is configuring the cluster and creating the database the “STATUS” will change from “Deploying” to “Healthy”, this may take a few minutes.

Once the cluster has been deployed, at this point you build your credential set and get your connection string to connect to the database that you have created. Optionally you can import the “travel-sample” data into the database.

You can skip this step as we will be creating data while performing CRUD operations, but this does bring in a nice dataset to play with.

If you select the “Settings” tab and then the “Database Access” menu item user “Security” settings you will be promoted to “Create Database Access”.

On the “Create Database Access” view, add a database access name, a password (don’t forget this!) and give it “All Scopes” and “Read/Write” access to the Travel-Sample bucket you created in the previous steps.

The next step is connecting to the database, to do this you will need to click the “Connect” tab which will up the connect view.

The “Public Connection String” is what you will use in your application to associate it with the database. You will need this in the next section.

The next thing to do is add an allowed list of IP Addresses to connect to your database.

Simple click in the “Allowed IP Addresses” link then click on the “Add Allowed IP” link and then either “Add Current IP Address” or “Allow Access from Anywhere” — note that if chose the former, your IP address may change as you switch networks and you will have to redo this step to connect. Finally, click the “Add Allowed IP” icon and you are finished here.

It seems like a lot of work, but it’s trivial compared to provisioning a 3 node cluster and doing the networking and configuration manually. Importantly, adding or removing nodes is simply a button click instead of having to get into gritty details of port mapping, etc.

Step 2: Setting up the Development Environment

At this point, we are ready to write some code! To do this using C#, you will need to install an editor and the .NET Framework. You can use any editor or IDE that you chose to use on any OS. If you want to use an editor, I suggest VSCode and then install the C# for Visual Studio Code extension. There is a nice tutorial for getting up and running with a console app here, if you need any help here I suggest you check it out!

Create a .NET Worker Service project in your editor or IDE. Two files will be added, one called Worker.cs and once called Program.cs. The Worker will be where you will write your code and the Program file will be the service configuration.

We will first add some NuGet dependencies to our *.csproj file for the the Couchbase .NET SDK and for the Dependency Injection module:

<Project Sdk="Microsoft.NET.Sdk.Worker">
   <PropertyGroup>
       <TargetFramework>net8.0</TargetFramework>
       <Nullable>enable</Nullable>
       <ImplicitUsings>enable</ImplicitUsings>
       <UserSecretsId>dotnet-Couchbase.Capella.Demo-64823687-EA08-4DF7-B39B-48D34081CE1B</UserSecretsId>
   </PropertyGroup>


   <ItemGroup>
       <PackageReference Include="Couchbase.Extensions.DependencyInjection" Version="3.4.13" />
       <PackageReference Include="CouchbaseNetClient" Version="3.4.13" />
       <PackageReference Include="Microsoft.Extensions.Hosting" Version="8.0.0"/>
   </ItemGroup>
</Project>

And then we will inject the Couchbase SDK into the .NET Worker process by editing the Program.cs file:

using Couchbase.Capella.Demo;
using Couchbase.Extensions.DependencyInjection;


var builder = Host.CreateApplicationBuilder(args);
builder.Services.AddHostedService<Worker>().
   AddCouchbase(options =>
{
   options.WithConnectionString("couchbases://cb.djgvxmbalokjeov3.cloud.couchbase.com");
   options.WithCredentials("[your user]", "[your password");
   options.ApplyProfile("wan-development");
}).
   AddCouchbaseBucket<INamedBucketProvider>("travel-sample");


var host = builder.Build();
host.Run();

The connection string, username and password are from the “Connect” tab on the Capella console we set up in step 1. We are applying the “wan-development” profile which changes the default settings of the SDK to something more compatible with the cloud environment of Capella vs an on-premise Couchbase deployment. These settings are generally lengthening the timeouts of the various services as latency is common in these environments.

Next we will add code to the Worker.cs file so that the Couchbase SDK dependency will be resolved and finally, add code to interact with Couchbase Capella.

public class Worker : BackgroundService
{
   private readonly ILogger<Worker> _logger;
   private readonly IClusterProvider _clusterProvider;


   public Worker(ILogger<Worker> logger, IClusterProvider clusterProvider)
   {
       _logger = logger;
       _clusterProvider = clusterProvider;
   }


   protected override async Task ExecuteAsync(CancellationToken stoppingToken)
   {
       var cluster = await _clusterProvider.GetClusterAsync();
       var bucket = await cluster.BucketAsync("travel-sample");
       var collection = bucket.DefaultCollection();
      
       while (!stoppingToken.IsCancellationRequested)
       {
           if (_logger.IsEnabled(LogLevel.Information))
           {
               _logger.LogInformation("Worker running at: {time}", DateTimeOffset.Now);
               var upsertResult = await collection.UpsertAsync("key1", new { Timestamp = DateTime.Now });
               _logger.LogInformation("Upserted 'key1' - CAS: {key1}", upsertResult.Cas);
               var getResult = await collection.GetAsync("key1");
               _logger.LogInformation($"The 'Key1' document: {getResult.ContentAs<dynamic>()}");


           }
           await Task.Delay(1000, stoppingToken);
       }
   }
}

First we add the IClusterProvider parameter to the constructor and assign it to a class variable. When the ExecuteAsync method is called by the worker process, the local ICluster, IBucket and ICouchbaseCollection variables will be assigned and then within the loop the “key1” document will be upserted and retrieved via Get.

With that we have a working application talking to a Capella cloud instance of Couchbase server. What is really cool is if at some point we wanted to scale up the database, all we would have to do is log back into the Capella console and then into “Settings” and “Services” and the increase the number of nodes, the CPU or any other setting while the app is running without bringing the application down.