Select Page


This continues my my “Getting Comfortable with Couchbase Mobile” series (post #5). This time we’ll look at exploring Sync Gateway from the command line. This can be really helpful, both for understanding and for testing/debugging.


To get comfortable with the whole Couchbase Mobile stack, it’s great to install and run everything on one 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.

Sync Gateway

Sync Gateway is a secure web gateway application with synchronization, REST, stream, batch and event APIs for accessing and synchronizing data over the web. Sync Gateway enables, among other things, secure data replication between Couchbase Server and Couchbase Lite.

Sync Gateway has few dependencies, and can run on most Linux distributions (even on the Raspberry Pi), Windows, and OSX/macOS. The specific steps for installation vary with platform. See the downloads site for all the available packages, and the full installation guide for complete details. To install on Linux distributions other than the supported ones, see this post.

Configuration and running

Once you have Sync Gateway installed, open up a command line shell.

Next, I have two configurations listed. You can either find these in the examples folder of your installation, or copy and paste the text here into your own.

The first you can use if you have Couchbase Server running on your machine. This is the configuration you’ll find in examples/basic-couchbase-bucket.json.

Or to just use Sync Gateway stand-alone (this is for testing only), use this configuration (found in examples/basic-walrus-bucket.json):

Creating a document

From the command line, run Sync Gateway and supply the path to the configuration file.

At this point the special GUEST user is enabled. We can go ahead and create a document.

The response shows the write succeeded. You can also see this in the Sync Gateway log output, and by looking at the backing bucket in the Couchbase Server Web Console.

Here’s the response we see on the command line.

Updating a document

Next, let’s try to make a change in the document.

The output shows this failed.

Why? If you recall from other parts of this blog series, Couchbase Mobile uses something called Multiversion Concurrency Control to track revisions. That means when we make changes to a document, we have to indicate what the “parent” document is.

Let’s try again, this time specifying the parent revision.

That works. The response is

Monitoring the changes feed

The changes feed gives you a great way to track the database. You can use this to write event-driven server side logic, or implement an automated conflict resolution system.

We’ll show a version that keeps the feed open. You might want to open another command line window to watch the output.

Here we’ve set the feed type to continuous. Various elements along a network path may close a connection that appears idle. Sync Gateway can send a heartbeat to prevent that. We set a timeout of 26000 milliseconds.

The last parameter, since, tells Sync Gateway where we want to start in the overall sequence of changes. You should normally treat this as an opaque value. Typically an app will start without specifying this parameter (getting all changes), then track the value sent back to use in future requests.

Here’s what a set of changes looks like.

Adding a user

Now, let’s add a new user, jdoe. This is an admin function, so the request has to go through the admin port. (Port 4985 if you’re using one of the listed configurations.)

We’ll also disable anonymous (GUEST) access.

We can no longer access Sync Gateway from the public port (4984) without supplying a username and password.


Let’s add a doc with a special field, channels.

You should see this returned.

Sync Gateway passes every document through a special function, called the sync function, whenever a document gets updated. We didn’t specify a sync function, so the default is automatically used.

The default function looks for channels in the document properties. If found, the document is assigned to that channel.

A user must have access to a channel to receive a document assigned to that channel. You can read more about channels here. We’ll see the impact coming up.

Just to see what happens when we don’t authenticate, try this command. The request gets rejected

with the expected response.

How about if we try again, supplying the right username and password?

This sometimes catches people by surprise. We get rejected again, but for a different reason.

What happened? Remember when we wrote the doc, we assigned it to channel abc. Even though user jdoe wrote the doc, we haven’t given access to the abc channel. Without that, jdoe isn’t allowed to read the doc back.

Change the channels jdoe has access to

and see that the user can now access the doc.


Wrapping up

Hopefully that gives some insight into Sync Gateway. I encourage you to check out the REST API further. You can find more interesting information looking at the Sync Gateway built-in web admin utility (http://localhost:4985/_admin/) and the Couchbase Server Web Console.

For an interesting example of using Sync Gateway stand-alone, see our talk from CouchBase Connect 2016:

This post originally appeared on

Share This