In this blog post you will get an overview of two related performance optimizations that you can do for Couchbase 2.5.1 and below. This is not for 3.x for reasons you can read at the bottom of this post. The two changes directly effect performance of reading and writing in Couchbase. Also know that you must have a properly sized cluster before you start messing with these settings. If you do not, you may cause more problems for the cluster than you solve. If you need more information about sizing your cluster, please see Perry’s execellent blog series on the topic.

Adding More Reader/Writer Threads Per Bucket

The first is changing the number of threads available on a per bucket basis. This should only be done if you have enough server/instance resources for this. If you are runing only 4 cores on your Couchbase nodes, this is probably not the performance enhancement for you. This setting will allow Couchbase to use more reader/writer threads and thus push more operations. So in the configuration of each bucket you will see a part of that screen that looks like this:

Optimizing More for Mixed Usage or Write heavy workloads

The second optimization links in with the first one. It has to do with optimizing Couchbase for either reading, writing or both. By default, Couchbase is optimized for reading thread wise and for many use cases, that works great. If you have mixed or a write heavy use case, you want to optimize Couchbase for that. You change these values with a REST API call like below with wget:

wget -O- –user= –password= –post-data=’ns_bucket:update_bucket_props(“”, [{extra_config_string, “workload_optimization=mix”}]).’ http://localhost:8091/diag/eval

The third option is to weight the threads towards writers:

wget -O- –user= –password= –post-data=’ns_bucket:update_bucket_props(“”, [{extra_config_string, “workload_optimization=write”}]).’ http://localhost:8091/diag/eval

If you want to set this back to the default, you’d do:

wget -O- –user= –password= –post-data=’ns_bucket:update_bucket_props(“”, [{extra_config_string, “workload_optimization=read”}]).’ http://localhost:8091/diag/eval

Note: All of the changes above REQUIRE a restart of the bucket to take effect. This is one of the very few off-line operations in CB. So do not change this on your production cluster without a planned maintenance window and planned down time!! For the changing of the number of threads, Couchbase will do that bucket restart for you once save it. For the REST calls, you will have to do it manually. Either way, plan appropriately for the down time!

For more information on this see the official documentation.

Is this still necessary for Couchbase 3.0?

No. These optimizations are no longer necessary in 3.x because of the introduction of a feature called the Global Thread Pool. With that feature, Couchbase now manages the the number of threads and the balance of threads dynamically for you and with intelligence as to your workload.


Posted by Kirk Kirkconnell, Senior Solutions Engineer, Couchbase

Kirk Kirkconnell was a Senior Solutions Engineer at Couchbase working with customers in multiple capacities to assist them in architecting, deploying, and managing Couchbase. His expertise is in operations, hosting, and support of large-scale application and database infrastructures.


  1. This requires bucket restart to take effect. Check with cbstats command does not show the updated parameter until after restart. Example:

    Default 2.5.1:

    /opt/couchbase/bin/cbstats localhost:11210 raw workload -b bucket -p password
    ep_workload:num_readers: 4
    ep_workload:num_shards: 4
    ep_workload:num_writers: 2
    ep_workload:policy: Optimized for read data access

    After restart:

    /opt/couchbase/bin/cbstats localhost:11210 raw workload -b bucket -p password
    ep_workload:num_readers: 3
    ep_workload:num_shards: 5
    ep_workload:num_writers: 5
    ep_workload:policy: Optimized for write data access

    1. Yep, good catch! The part where I state about the restarting needs to be pushed down to the end of the article. I will fix the article.

  2. Yep, good catch! The part where I state about the restarting needs to be pushed down to the end of the article. I will fix it.

Leave a reply