Posts tagged with 'Couchbase Server'

This is a repost that originally appeared on the Couchbase Blog: Documentation Contribution and Improvements.

Documentation is undergoing some changes for the better at Couchbase. Matt Carabine and the documentation team have been working to improve the build process, backporting, and review. And, they have made it easier to contribute to documentation in the process.

Contributing to the documentation

Couchbase documentation is open source, but until recently, there were a number of problems. If you were looking to make a substantial change or maybe just fix a quick typo, you were faced with one or more of these questions:

  • Where do I look to make a change?

  • What file do I change?

  • What file maps to the doc page I’m looking at?

  • How do I change it?

It was not always clear how to go from a documentation URL to a specific file in the Github repository.

Now, that’s changed. If you visit a page in the documentation, you will notice an "Edit on GitHub" link on each page. Click this link and you’ll be taken to GitHub to edit the file directly (your first time, you will be prompted to create a fork).


First, visit the Using Graceful Failover page in the documentation.

Next, click the "Edit on GitHub" link.

Documentation edit on GitHub link

At this point, you’re on GitHub. Assuming you’ve used Git/GitHub before, the rest of this process should be familiar.

If you’ve not already created a fork, you will be prompted to do so.

After that, you will see an edit screen where you can make your change.

Once you’ve made a change, click the "Propose file change". You’ll see a diff, and you’ll be able to create a pull request.

Contribution guide

That’s a crash course on contributing to the documentation. There’s a full guide on how to contribute to Couchbase Server docs.

Note that while that guide is written in Markdown, Couchbase Server documentation is written in the Darwin Information Typing Architecture (DITA) markup language.

For simple typo corrections, you may not need to know much about DITA, but for deeper edits, you will need to familiarize yourself with the syntax and/or an editing tool like Oxygen.

Documentation contributions

Thank you to those in the community who have already contributed! This new system has only been going for a few months, but we’ve already gotten some great contributions. So I tip my hat to:

It astounds me that we had such great contributions from so many people so quickly! Thank you, everyone, for helping to make the documentation better.

How did we get here?

To make contribution easier, the build process had to be improved. Previously, it involved a bunch of manual steps: pull source, build locally, zip up the results, FTP them to a server, run one or more slow build server tasks manually. Now you’ll see that the build step happens much more quickly in the pull request, and previews are generated quickly.

The reviewing of content was also improved. Previously, previews were only possible on a single location. There was no simultaneous reviewing possible. This, combined with the slow, manual builds, was frustrating, and made it difficult to review all changes, let alone external ones.

Finally, backporting to other versions of Couchbase Server documentation was also a problem. The documentation is stored in separate branches for each version, so if an issue is raised and fixed in 4.6, it may also apply to 4.5, and so on. That’s a very manual process, but a @cb-docs-robot was created to automate the backporting (which you’ll see in many of the above examples).

How are we doing?

Another thing we’ve added is the ability to give us feedback on the documentation right from your browser.

Documentation feedback

Simply find the "Feedback On This Page" button at the bottom right of your browser, click it, and write feedback.


These documentation improvements help us both internally and externally. We hope that it will make your experience with the documentation less frustrating and more enjoyable. We welcome your feedback! Please check out the Couchbase docs on GitHub.

This is a repost that originally appeared on the Couchbase Blog: Tooling Improvements in Couchbase 5.0 Beta.

Tooling improvements have come to Couchbase Server 5.0 Beta. In this blog post, I’m going to show you some of the tooling improvements in:

  • Query plan visualization - to better understand how a query is going to execute

  • Query monitoring - to see how a query is actually executing

  • Improved UX - highlighting the new Couchbase Web Console

  • Import/export - the new cbimport and cbexport tooling

Some of these topics have been covered in earlier blog posts for the developer builds (but not the Beta). For your reference:

Query Plan Visualization tooling

In order to help you write efficient queries, the tooling in Couchbase Server 5.0 has been enhanced to give you a Visual Query Plan when writing N1QL queries. If you’ve ever used the Execution Plan feature in SQL Server Management Studio, this should feel familiar to you.

As a quick example, I’ll write a UNION query against Couchbase’s travel-sample bucket (optional sample data that ships with Couchbase Server). First, I’ll click "Query" to bring up the Couchbase Query Workbench. Then, I’ll enter a query into the Query Editor.

Query Editor tooling

This is a relatively complex query that involves the following steps (and more):

  1. Identify and scan the correct index(es)

  2. Fetch the corresponding data

  3. Project the fields named in the SELECT clause

  4. Find distinct results

  5. UNION the results together

  6. Stream the results back to the web console

In Couchbase Server 4.x, you could use the EXPLAIN N1QL command to get an idea of the query plan. Now, in Couchbase Server 5.0 beta, you can view the plan visually.

Query Plan Visualization tooling

This tooling shows you, at a glance, the costliest parts of the query, which can help you to identify improvements.

Query monitoring

It’s important to have tooling to monitor your queries in action. Couchbase Server 5.0 beta has tooling to monitor active, completed, and prepared queries. In addition, you have the ability to cancel queries that are in progress.

Start by clicking "Query" on the Web Console menu, and then click "Query Monitor". You’ll see the "Active", "Completed", and "Prepared" options at the top of the page.

Let’s look at the "Completed" queries page. The query text and other information about the query is displayed in a table.

Query Monitor of completed queries

Next, you can sort the table to see which query took the longest to run (duration), return the most results (result count), and so on. Finally, if you click "edit", you’ll be taken to the Query Workbench with the text of that query.

New Couchbase Web Console

If you’ve been following along, you’ve probably already noticed the new Couchbase Web Console. The UI has been given an overhaul in Couchbase Server 5.0. The goal is to improve navigation and optimize the UI.

New Couchbase Web Console

This new design maximizes usability of existing features from Server 4.x, while leaving room to expand the feature set of 5.0 and beyond.

cbimport and cbexport

New command line tooling includes cbimport and cbexport for moving data around.

cbimport supports importing both CSV and JSON data. The documentation on cbimport should tell you all you want to know, but I want to highlight a couple things:

  • Load data from a URI by using the -d,--dataset <uri> flags

  • Generate keys according to a template by using the -g,--generate-key <key_expr> flags. This gives you a powerful templating system to generate unique keys that fit your data model and access patterns

  • Specify a variety of JSON formats when importing: JSON per line (lines), JSON list/array (list), JSON ZIP file/folder containing multiple files (sample). So no matter what format you receive JSON in, cbimport can handle it.

For more about cbimport in action, check out Using cbimport to import Wikibase data to JSON documents.

cbexport exports data from Couchbase to file(s). Currently, only the JSON format is supported. Again, the documentation on cbexport will tell you what you want to know. A couple things to point out:

  • Include the document key in your export by using the --include-key <key> flag.

  • Export to either "lines" or "list" format (see above).

Here’s an example of cbexport in action (I’m using Powershell on Windows, but it will be very similar on Mac/Linux):

PS C:\Program Files\Couchbase\Server\bin> .\cbexport.exe json -c localhost -u Administrator -p password -b mybucketname -f list -o c:\exportdirectory\cbexporttest.json --include-key _id

Json exported to `c:\exportdirectory\cbexporttest.json` successfully

PS C:\Program Files\Couchbase\Server\bin> type C:\exportdirectory\cbexporttest.json

{"_id":"463f8111-2000-48cc-bb69-e2ba07defa37","body":"Eveniet sed unde officiis dignissimos.","type":"Update"},
{"_id":"e39375ab-2cdf-4dc4-9659-6c19b39e377d","name":"Jack Johnston","type":"User"}

Notice that the key was included in an "_id" field.


Tooling for Couchbase Server 5.0 beta is designed to make your life easier. These tools will help you whether you’re writing queries, integrating with data, monitoring, or performing administrative tasks.

We’re always looking for feedback. Inside of the Web Console, there is a feedback icon at the bottom right of the screen. You can click that to send us feedback about the tooling directly. Or, feel free to leave a comment below, or reach out to me on Twitter @mgroves.

This is a repost that originally appeared on the Couchbase Blog: Logging with Log4Net and Common Logging.

Logging with Common.Logging, log4net, and the Couchbase .NET SDK is demonstrated in this video.

The source code for the logging example used in this video is available on Github.

For more information about logging, check out the logging documentation on the developer portal.

If you have questions or feedback, please contact me at, or on @mgroves at Twitter, or just leave a comment below.

This is a repost that originally appeared on the Couchbase Blog: Authentication and Authorization with RBAC in .NET.

Authentication and authorization are vastly improved in Couchbase Server 5.0. We’ve been blogging about the new RBAC features in the developer preview for a while.

Now that Couchbase Server 5.0 is released, I’m writing a more in-depth blog post about how to use the Couchbase .NET SDK along with these new features.

The full code samples used in this blog post are available for you on Github.

Create a bucket

As I mentioned in the previous posts, the days of buckets with passwords are gone. The future belongs to users—​users that have specific permission(s) to specific bucket(s).

Let’s start by creating a bucket. In the Couchbase UI, login as the Administrator that you created when you installed Couchbase. Go to "Buckets" and click "ADD BUCKET" (top right). You will see the "Add Data Bucket" dialog. Notice that there is no longer a "password" field (not even in "Advanced bucket settings").

Add new bucket - no authentication options anymore

Give the bucket a name and some amount of memory, and click "Add Bucket". Now you have a bucket. But, other than an Administrator in the UI, no one can access this bucket yet.

Create a user

In order to get access to this bucket, you must create a user. In Couchbase 5.0, "users" are an entirely new feature, bringing richer authentication and authorization features to Couchbase Server.

While still logged in as an administrator, go to "Security" to see a list of users. Click "ADD USER" (top right).

Adding a new user for authentication and authorization

Create a user with whatever name and password you’d like. You can choose which roles the user has, and for which buckets (when applicable). Let’s give this user Data Writer and Data Reader roles, for the bucket that was just created (e.g. "mybucket"), but NOT any Query roles.

Adding authorization for data read and data write

Once the user is added, you can hover over the roles to get a description of what the role means.

Authorization tool tip

Authentication and authorization with the Couchbase .NET SDK

Now that we have a bucket and a user, let’s see how to use them with the .NET SDK.

Start by creating a Cluster object.

var cluster = new Cluster(new ClientConfiguration
    Servers = new List<Uri> { new Uri("http://localhost:8091") }

You have a cluster, but your program has not been authenticated yet. Use a PasswordAuthenticator object to specify the credentials. Then, use that object with the cluster’s Authenticate method. In this example below, I’m using incorrect credentials.

var authenticator = new PasswordAuthenticator("myuser", "wrongpassword");

Now, if I try to perform an operation like OpenBucket on the cluster, an exception is thrown.

    var bucket = cluster.OpenBucket("mybucket");
catch (Exception ex)
    Console.WriteLine("Error getting bucket.");

Error in authentication

Now, let’s try it again using the correct credentials. Authentication will work. But let’s talk about authorization next.

Remember that I only gave this user Data Writer and Data Reader roles (for mybucket). So, if I authenticate and insert a document now, it works.

var cluster = new Cluster(new ClientConfiguration
    Servers = new List<Uri> { new Uri("http://localhost:8091") }
var authenticator = new PasswordAuthenticator("myuser", "password");
var bucket = cluster.OpenBucket("mybucket");

// insert a document, this should be allowed
var result = bucket.Insert(Guid.NewGuid().ToString(), new {foo = "bar"});
Console.WriteLine("Insert was successful: " + result.Success);

Console output when authentication and authorization are valid

But if I tried to, for instance, execute a N1QL (SQL for JSON) query, then it would fail. This is because that user is not authorized to execute queries.

var queryResult = bucket.Query<int>("SELECT COUNT(1) FROM `" + bucket.Name + "`");
Console.WriteLine("Query was successful: " + queryResult.Success);
queryResult.Errors.ForEach(e => Console.WriteLine("Error: " + e.Message));

I’m just doing a simple COUNT(1) aggregation query. Since that user is not authorized, here’s what’s displayed:

No authorization for running a query

One more thing

If you are worried about the effect this will have on upgrading from Couchbase Server 4.x to Couchbase Server 5.0, then here’s a tip. If you create a user with the same name as the bucket (e.g. a bucket called "foo" and a user named "foo"), then the older Couchbase .NET APIs that still expect a bucket password will work as before. Just give that user a "Cluster Admin" role for now. This is a good temporary fix until you can re-engineer your system to use a regimented approach to role.


Couchbase Server 5.0 is out now in beta! These role-based authentication (RBAC) features make Couchbase a leader in document database security, and I’m personally very pleased that Couchbase is going in this direction. Security is important, but too often overlooked by developers.

If you have any questions, please ask away in the Couchbase Forums, leave a comment below, or ping me on Twitter @mgroves.

This is a repost that originally appeared on the Couchbase Blog: Authorization and Authentication with RBAC (Part 2).

Authorization and authentication are important to Couchbase. In March, I blogged about some of the new Role Based Access Control (RBAC) that we are showing in the Couchbase Server 5.0 Developer Builds. This month, I’d like to go into a little more detail now that the April Couchbase Server 5.0 Developer Build is available (make sure to click the "Developer" tab).

Authentication and authorization

In past version of Couchbase, buckets were secured by a password. In 5.0, bucket passwords for authorization are gone. You can no longer create a "bucket password" for authorization. Instead, you must create one (or more) users that have varying levels of authorization for that bucket. Notice that there is no "password" field anymore (not even in the "Advance bucket settings":

Create a new Couchbase bucket - no password for authorization

So now, you no longer have to hand out a password that gives complete access to a bucket. You can fine-tune bucket authorization, and give out multiple sets of credentials with varying levels of access. This will help you tighten up security, and reduce your exposure.

Note: The administrator user still exists, and has permission to do everything. So I can still run N1QL queries (for instance) on that bucket while logged in as an administrator account. However, this is not the account you should be using from your clients.

Creating an authorized user

To create a new user, you must be logged in as an administrator (or as a user that has an Admin role). Go to the "Security" tab, and you’ll be able to see a list of users, and be able to add new ones.

Create a new user by clicking "ADD USER". Enter the information for the user. You may want to create a user for a person (e.g. "Matt"), or you may want to create a user for a service (e.g. "MyAspNetApplication"). Make sure to enter a strong password, and then select the appropriate roles for the user you want to create.

For example, let’s create a user "Matt" that only has access to run SELECT queries on the bucket I just created. In "Roles", I expand "Query Roles", then "Query Select", and check the box for "mynewbucket", and then "Save" to finalize the user.

Create a new user with authorization to run a select query

Authorization in action

When I log out of the administrator account, and log back in as "Matt", I can see that the authorization level I have is severely restricted. Only "Dashboard", "Servers", "Settings", and "Query" are visible. If I go to "Query" I can execute SELECT 1;

Execute SELECT query logged in with only Query authorization

If I try something more complex, like SELECT COUNT(1) FROM mynewbucket, I’ll get an error message like:

    "code": 13014,
    "msg": "User does not have credentials to access privilege cluster.bucket[mynewbucket]!read. Add role Data Reader[mynewbucket] to allow the query to run."

So, it looks like I have the correct authentication to log in, and I have the correct authorization to execute a SELECT, but I don’t have the correct authorization to actually read the data. I’ll go back in as admin, and add Data Reader authorization.

User now has authorization for two roles

At this point, when I login with "Matt", SELECT COUNT(1) FROM mynewbucket; will work. If you are following along, try SELECT * FROM mynewbucket;. You’ll get an error message that no index is available. But, if you try to CREATE INDEX you’ll need another permission to do that. You get the idea.

New N1QL functionality

There’s some new N1QL functionality to go along with the new authentication and authorization features.


You can grant and revoke roles with N1QL commands. You need Admin access to do this.

Here’s a quick example of granting SELECT query authorization to a user named "Matt" on a bucket called "mynewbucket":

GRANT ROLE query_select(`mynewbucket) TO Matt;`

And likewise, you can REVOKE a role doing something similar:

REVOKE ROLE query_select(`mynewbucket) FROM Matt;`

Creating users with REST

There is no way (currently) to create users with N1QL, but you can use the REST API to do this. Full documentation is coming later, but here’s how you can create a user with the REST API:

  • PUT to the /settings/rbac/users/builtin/<username> endpoint.

  • Use admin credentials for this endpoint (e.g. Administrator:password with basic auth)

  • The body should contain:

    • roles=<role1,role2,…​,roleN>

    • password=<password>

Below is an example. You can use cURL, Postman, Fiddler, or whatever your favorite tool is to make the request.

Headers: Content-Type: application/x-www-form-urlencoded Authorization: Basic QWRtaW5pc3RyYXRvcjpwYXNzd29yZA==

Body: roles=query_select[mynewbucket],query_update[mynewbucket]&password=password

The above assumes that you have an admin user/password of Administrator/password (hence the basic auth token of QWRtaW5pc3RyYXRvcjpwYXNzd29yZA==).

After executing that, you’ll see a new user named "restman" with the two specified permissions.

Create a new user with a REST command

Wait, there’s more!

The RBAC system is far too rich to cover in a single blog post, and full documentation is on its way. In the meantime, here are some details that might help you get started with the preview:

  • You may have noticed the all option in the screenshots above. You can give a user roles on a bucket-by-bucket basis, or you can give permission to all buckets (even buckets that haven’t been created yet.

  • I covered FTS permissions in the previous blog post, but there are permissions that cover just about everything: views, bucket administration, backup, monitoring, DCP, indexes, etc.

  • You can’t create buckets with a password anymore. The equivalent is to instead create a user with the name as the bucket, and give it authorization to a role called "Bucket Full Access". This will be useful for upgrading and transitioning purposes.

We still want your feedback!

Stay tuned to the Couchbase Blog for information about what’s coming in the next developer build.

Interested in trying out some of these new features? Download Couchbase Server 5.0 April 2017 Developer Build today!

The 5.0 release is fast approaching, but we still want your feedback!

Bugs: If you find a bug (something that is broken or doesn’t work how you’d expect), please file an issue in our JIRA system at or submit a question on the Couchbase Forums. Or, contact me with a description of the issue. I would be happy to help you or submit the bug for you (my Couchbase handlers let me take selfies on our cartoonishly big couch when I submit good bugs).

Feedback: Let me know what you think. Something you don’t like? Something you really like? Something missing? Now you can give feedback directly from within the Couchbase Web Console. Look for the feedback icon icon at the bottom right of the screen.

In some cases, it may be tricky to decide if your feedback is a bug or a suggestion. Use your best judgement, or again, feel free to contact me for help. I want to hear from you. The best way to contact me is either Twitter @mgroves or email me

Matthew D. Groves

About the Author

Matthew D. Groves lives in Central Ohio. He works remotely, loves to code, and is a Microsoft MVP.

Latest Comments