Getting Comfortable with Couchbase Mobile: Couchbase Server via the Command Line

Introduction

This will be the third post in a series about the Couchbase Mobile stack. You can find the first and second posts here and here, respectively. They cover installing Couchbase Server and some interesting bits of Couchbase Web Console. In this post we’ll talk about working with Couchbase Server from the command line.

Background

To get comfortable with the whole stack, it’s great to install and run everything on your development machine. In this series of posts, I’ll walk through the steps get to started with each component. I’ll show how to do a little extra exploring along the way, too.

I’ll only do minimal configuration. This is not intended to explain what you need for a production environment. I assume you’re familiar with some basics of NoSQL, have some understanding of Couchbase, and know how to build apps in something like Java, Android, or iOS. If you want to read up on NoSQL databases or Couchbase, you can find lots of resources on the Couchbase site.

Couchbase is open-source. Everything I’ll use here is free to try out. See the end of the post for more resources if you need help.

Command Line

Couchbase Server has quite a number of command line tools. It also has an extensive REST API. Let’s take a look at a few interesting points.

Command Line Utilities

On a Mac, you can usually find the command line tools in /Applications/Couchbase Server.app/Contents/Resources/couchbase-core/bin.

You can find out the command locations for Linux and Windows here: http://developer.couchbase.com/documentation/server/current/cli/cli-intro.html

couchbase-cli: The Command Line Cluster Management Tool

This tool can work on single nodes or entire clusters. It supports commands for everything from manipulating buckets to cross-data center replications. Here are just a few examples.

Server list

This next command will return a brief list of servers in a cluster.

Output

As we’d expect, this shows we have one active server running locally.

(Note: for brevity I’ll leave off the cluster, username, and password options going forward. You’ll need them for the actual commands, though.)

Collecting logs

We can turn on logging. There are options to automatically upload the data for support.

Output

Next, check the status.

Output

And stop logging.

Output

The log files are extensive. The sample here contained many files and over a megabyte of information. It’s all text you can look through. If you ever need support for a CB Server installation, it’s good to know how to get this data.

cbq: The Command Line Shell for N1QL

The other tool we’ll look at is cbq, the interactive shell for running N1QL queries.

In this case, the command will loop prompting us for input. Start by running with no options.

You should immediately see a couple of notices and the command prompt.

Create a primary index

To run queries, you’ll at least need a primary index. Some versions of the beer-sample data come with one, some don’t.

Output

Running queries

Here’s an example of a fairly simple query.

Output

We’ve pulled all the beers that have “Imperial” as part of their style description.

Notice the back ticks around beer-sample. These are needed because of the dash in the name.

N1QL should look familiar if you know SQL. N1QL is a superset of SQL. JSON data often isn’t flat like relational data. N1QL has extensions to do things like unroll arrays. You can read more about N1QL here.

To understand N1QL in more depth, I recommend trying out this great interactive tutorial.

You can find a helpful post by Nic Raboy on more advanced features of cbq here.

REST API

Couchbase Server has an extensive set of REST endpoints. Most of them have to do with managing deployments.

I will show examples using curl. There’s a really nice tool that I recommend as a replacement for curl, httpie. It’s a little easier to use, and creates colorized output. I won’t use it here since curl is more commonly found.

I find other endpoints interesting see what they produce, but for our purposes I’m going to focus on queries.

View queries

In a my previous post on the Couchbase Web Console, we took a look at Views. Views create a static index that you can use to retrieve information. You can control the response with a number of options. Much of the value of Views comes from how you define the map/reduce functions, but these options further enhance using Views to query data. Filtering by key is especially useful. Let’s take a look.

You access Views using URIs of the form

For our beer sample, we can get all the brewery and beer information like this.

That outputs a lot of information. Here’s just a short sample of the output.

You can see the key information. We can use this to narrow the results. Here’s an example using a single key.

And the result.

Notice I added a -g flag. Curl by default allows certain types of pattern matching (globbing). This works using the special characters {} and []. We need those to specify the key in JSON. The easiest way is to turn globbing off. Don’t forget the single quotes around the parameter, too.

That example filtered by one key. Here’s one that shows how to get results matching more than one at a time.

Notice the output isn’t sorted.

Beyond the use in debugging (or just understanding what’s going on with) views, I’ve seen some cool things written just using shell scripts and this kind of querying.

N1QL queries

Turns out you can run N1QL queries from the command line, too. Here’s a simple example pulling everything from the beer sample bucket.

The output includes some stats and the full documents. (The stats are output to stderr on a Mac).

The N1QL command must have certain characters encoded to work properly. In this case, you can probably guess that %20 is the encoding for a single space. You can read more about that on this Stack Overflow post.

Next Steps

We’ve spent a good amount of time looking at Couchbase Server. Next we’ll jump into mobile by taking a dive into Sync Gateway. I’ll follow roughly the same format. In the case of Sync Gateway, though, we’ll see there’s a lot more to do using the REST APIs. This will include some tricks to help with diagnosing common problems. After that we’ll look at Couchbase Lite, and then wrap everything up by looking at data moving from end-to-end through the complete stack. Stay tuned.

[buttongroup][button style=”btn-link btn-lg” icon=”fa fa-arrow-left” align=”left” iconcolor=”#dd3333″ type=”link” target=”false” title=”Previous: Couchbase Web Console” link=”https://www.couchbase.com/blog/comfortable-couchbase-mobile-couchbase-web-console/” linkrel=””][button style=”btn-link btn-lg” icon=”fa fa-arrow-right” align=”left” iconcolor=”#dd3333″ type=”link” target=”false” title=”Next: Installing Sync Gateway” link=”https://www.couchbase.com/blog/getting-comfortable-couchbase-mobile-installing-sync-gateway/” linkrel=””][/buttongroup]

Postscript

Check out more resources on our developer portal and follow us on Twitter @CouchbaseDev.

You can post questions on our forums. And we actively participate on Stack Overflow.

You can follow me personally at @HodGreeley