Configuring the client

Configuring the client

While the client comes with reasonable default configuration settings, sometimes you need to customize the configuration for your unique environment or use case.

Programmatic configuration

The client comes with a set of default values for its configuration. For the most part, these defaults are satisfactory for most development and production use. However, these values can be modified or overridden as needed to tune the client to specific use-cases and scenarios. The client can be configured in one of two ways: programmatically through the ClientConfiguration object or the App.Config or Web.Config. You should choose one of the two in order to avoid precedence problems and configuration clashes.

The ClientConfiguration object

The client can be configured programmatically using the ClientConfiguration class and passing the custom configuration through one of the Cluster constructor overloads. Through the ClientConfiguration you can also configure individual buckets and their connection pools.

Here is an example of overriding the default configuration settings with several overrides:

ClientConfiguration example

var config = new ClientConfiguration
{
  Servers = new List<Uri>
  {
    new Uri("http://192.168.56.101:8091/pools"),
    new Uri("http://192.168.56.102:8091/pools"),
    new Uri("http://192.168.56.103:8091/pools"),
    new Uri("http://192.168.56.104:8091/pools"),
  },
  UseSsl = true,
  DefaultOperationLifespan = 1000,
  BucketConfigs = new Dictionary<string, BucketConfiguration>
  {
    {"default", new BucketConfiguration
    {
      BucketName = "default",
      UseSsl = false,
      Password = "",
      DefaultOperationLifespan = 2000,
      PoolConfiguration = new PoolConfiguration
      {
        MaxSize = 10,
        MinSize = 5,
        SendTimeout = 12000
      }
    }}
  }
};

using (var cluster = new Cluster(config))
{
  IBucket bucket = null;
  try
  {
    bucket = cluster.OpenBucket();
    //use the bucket here
  }
  finally
  {
    if (bucket != null)
    {
      cluster.CloseBucket(bucket);
    }
   }
  }
}
		

At the top of the snippet, the code creates the ClientConfiguration object and uses property initializers to override the default settings. It then creates the bootstrap list of servers for initiating communication between the client and the cluster. The client attempts to bootstrap off of each of these servers. When it successfully connects with one of the servers in this list, the bootstrapping process ends.

Why add more than one server to the bootstrap (Servers) list? It’s possible that one or more of the servers in that list might not be part of the cluster at the time the client is created. By providing a range of nodes as bootstrap candidates, the likelihood of the client finding a suitable node to connect to increases. After the client successfully bootstraps, it receives a server configuration of the current state of the cluster. It uses this server configuration to update the bootstrap list by adding any additional candidate bootstrap servers to it.

Here are all of the ClientConfiguration members and their defaults:

Table 1. ClientConfiguration properties
Name Description Default
UseSsl Whether or not to use SSL encrypt data being sent to and from the server false
SslPort Overrides the DirectPort and sets the SSL port to use for key-value operations using the binary memcached protocol id UseSsl is enabled 11207
ApiPort The port to use for the Views API 8092
DirectPort The port to use for standard memcached binary operations such as storing and retrieving documents by key 11210
MgmtPort The port to use for the Management API 8091
HttpsMgmtPort Overrides the MgmtPort and sets the SSL port to use for the Management API 18091
HttpsApiPort Overrides the ApiPort and sets the SSL port to use for the Views API 18092
OperationTimeout The amount of time the client will wait on a pending operation before timing out 2500 ms
ObserveInterval The interval to wait before each Observe attempt 10 ms
ObserveTimeout The maximum amount of time to wait before timing out 500 ms
Servers The list of servers to bootstrap from http://localhost:8091/pools
MaxViewRetries The upper limit for the number of times a View request that has failed will be retried 2
ViewHardTimeout The maximum amount of time that a View request takes before timing out. This includes time for retries. 30000 ms
ViewRequestTimeout Sets the timeout for each HTTP View request. 5000 ms
HeartbeatConfigInterval Sets the interval for configuration "heartbeat" checks, which check for changes in the configuration that are otherwise undetected by the client. 10000 ms
EnableConfigHeartBeat Enables configuration heartbeat checks. true
DefaultConnectionLimit Gets or sets the maximum number of concurrent connections allowed by a ServicePoint object used for making View and N1QL requests. 5
MaxServicePointIdleTime Gets or sets the maximum idle time of a ServicePoint object used for making View and N1QL requests. 100,000 ms
Expect100Continue Gets or sets a Boolean value that determines whether 100-Continue behavior is used.  
DefaultOperationLifespan Gets or sets the default maximum time an operation is allowed to take (including processing and in-flight time on the wire). Note that in App.config this is set via operationLifespan 2500ms

In the ClientConfiguration example code snippet, the UseSsl property is set to true, indicating that all traffic between the client and the cluster will be encrypted. To use this feature, the server hosting the application needs to have the appropriate certificate installed and the cluster must be Couchbase Server version 3.0 or later.

The ClientConfiguration example specifies a configuration for the default bucket. Providing a bucket level configuration overrides any configuration settings set at the cluster level. The BucketConfiguration members and their defaults are as follows:

Table 2. BucketConfiguration properties
Name Description Default
BucketName The name of the bucket to connect to. "default"
UseSsl Whether or not to use SSL encrypt data being sent to and from the server false
Password The bucket password empty string
ObserveInterval The interval to wait before each Observe attempt 10ms
ObserverTimeout The max amount of time to wait before timing out 500ms
PoolConfiguration The TCP socket pool configuration (see below)
DefaultOperationLifespan The default lifespan for operations of this bucket (i.e. maximum time taken by the operation, including processing and in-flight time on the wire). Note that in App.config this is set via operationLifespan 2500ms

Finally, in the ClientConfiguration example code snippet, it provides a new PoolConfiguration, which overrides the default MaxSize and MinSize of 2 and 1 respectively, with the values 5 and 2. This means that the pool will start with 2 TCP connections and grow to 5 TCP connections on demand.

The rest of the PoolConfiguration members and their defaults:

Table 3. PoolConfiguration properties
Name Description Default
MaxSize The maximum number of TCP connection to use 2
MinSize The minimum or starting number of TCP connections to use 1
WaitTimeout The amount of time to wait for a TCP connection before timing out after the MaxSize has been reached and all connections are being used 2500 ms
ShutdownTimeout The amount of time to wait before the underlying socket closes its connection 10000 ms
SendTimeout The amount of time to allow between an operation being written on the socket and being acknowledged. 15000 ms
UseSsl Whether or not to use SSL encrypt data being sent to and from the server false

The example source can be found on GitHub here.

Configuration with an App.Config or Web.Config

As an alternative to using programmatic configuration, you can also configure the client through an App.config or Web.config. The following snippet illustrates how you would do so:


<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <configSections>
    <sectionGroup name="couchbaseClients">
      <section name="couchbase"
               type="Couchbase.Configuration.Client.Providers.CouchbaseClientSection, Couchbase.NetClient"/>
    </sectionGroup>
  </configSections>
  <couchbaseClients>
    <couchbase useSsl="false" operationLifeSpan="1000">
      <servers>
        <add uri="http://192.168.56.101:8091/pools"></add>
        <add uri="http://192.168.56.102:8091/pools"></add>
        <add uri="http://192.168.56.103:8091/pools"></add>
        <add uri="http://192.168.56.104:8091/pools"></add>
      </servers>
      <buckets>
        <add name="default" useSsl="false" password="" operationLifespan="2000">
          <connectionPool name="custom" maxSize="10" minSize="5" sendTimeout="12000"></connectionPool>
        </add>
      </buckets>
    </couchbase>
  </couchbaseClients>
    <startup>
        <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.5.1" />
    </startup>
</configuration>
		

This the same configuration programmatically defined earlier in this section using the ClientConfiguration class.

To use this configuration, you need to use one of the special Cluster constructors that takes a string containing the path of the configuration:


using (var cluster = new Cluster("couchbaseClients/couchbase"))
{
  using (var bucket = cluster.OpenBucket())
  {
    //use the bucket here
  }
}
			

That the string couchbaseClients/couchbase matches the path of the sectionGroup and section elements in the App.config defined above. This example can be found on Github here.