A newer version of this documentation is available.

View Latest

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.