Part 3: Adding sync functionality to a centralized server

This multipart blog will help the reader build an end-to-end mobile application using the industry-leading features of Couchbase Lite. 

A state of the art, end-to-end, scalable and production grade application should include the following features:

    • An embedded database to store data locally on-device to reduce network trips to a centralized database for every activity. This goes a long way in improving user experience.
    • Perform full text searching on the device.
    • Sync with peer mobile devices and a centralized server.

This blog post series is divided into four parts:

    • Part 1 showcases the process for building a mobile application that leverages CB Lite and uses it as an embedded database to store data.
    • Part 2 shows how to run Full Text Search (FTS) on the device.
    • Part 3 introduces syncing with a centralized Couchbase server from edge devices.
    • Part 4 will demonstrate peer-to-peer syncing between devices.

We are building this app on top of Couchbase Server and with Couchbase Mobile used on the device and for sync management.

Couchbase is an award-winning distributed NoSQL cloud database. It delivers unmatched versatility, performance, scalability, and financial value across cloud, on-premises, hybrid, distributed cloud, and edge computing deployments.

The Couchbase Mobile portfolio includes:

    • An embedded database for edge devices.
    • A high performance Sync Gateway that provides peer-to-peer and centralized server sync features.
    • Edge datacenters powered by Couchbase Server that can be deployed on the cloud, on-prem or locally.

Diagram of the Couchbase Mobile portfolio

Adding the Sync functionality

The code for this tutorial is available in my couchbasemobile GitHub repository. We are working with the RateIt application that is part of the file, extract its files to a local folder.

Alternatively, you can follow the instructions in this blog series to build the app from scratch.

The app’s functionality is divided into three parts:

    1. sending requests
    2. receiving requests from others
    3. viewing the request you’ve sent

Send rating requests

The app that we build in this tutorial will allow users to send a topical rating request to a person and receive any responses.

A SEND TO field indicates the phone number of the person to whom you want to send the request. 

The Message field indicates what you want them to do with it. In this case, since it is a rating request, I have a predefined message of: “Rate 1-5” – indicating they need to supply a rating when they send the request back.

The Subject field indicates any topic on which you want a rating, for example, it can just be a word or phrase like:

    • Actor: Chris Hemsworth
    • Book: Pride and Prejudice

There are not any strict input validations on the fields, but that is something you would do for a production-grade mobile app.

When you click SEND, a request is sent to the target person.

Software prerequisites

In this part of the blog, we require the following software to be installed on a desktop or server that your mobile app will access.

Couchbase Server – Install a version on your local laptop or server using this free download link. Once successfully installed you should be able to access the Couchbase console from your browser at http://localhost:8091.

Couchbase Server download page

Sync Gateway Server – This can be on the same dev machine as Couchbase Server. Download Sync Gateway here and review the documentation here.

Couchbase Mobile Sync Gateway download page

Follow all of the Start Here! steps from the documentation, highlighted here in green.

Couchbase Sync Gateway setup docs

To get started, do the following:

    • Start Sync Gateway on your laptop.
    • Complete all steps in the verification section.
    • Give the user access to all channels with this curl statement:


Introducing the RateIt Mobile Application

As shown in the previous posts, the main page of the app has three buttons:


We will be adding UI components to let you switch sync on and off, as well as providing a text input for users to identify themselves.

The code files we will be manipulating are and activity_main.xml.

Syncing from the mobile device to the centralized server is for apps that need to constantly update a centralized server with any changes from the handheld devices. This syncing will apply those changes to other devices if they also share the same application and centralized database connection.


Reviewing the server sync code

Add the following code to activity_main.xml to incorporate the sync switch. It is an on/off switch that lets the user decide when to enable sync.

The following XML snippet takes the username as input from the user and has a label associated to make it user friendly.

The app frontpage will now look like this, note the new components on the top row:

Couchbase Mobile app with new UI components

We’ll now update in the Java → com.example.rateit folder with these changes:

    • Add code that checks if the sync button needs to be toggled.
    • Also add code to get the input from the user input field


 Add a listener for the sync toggle button that does the following:

      • When the toggle button is changed from ON to OFF, or vice versa, it will listen and act on these changes.
      • When the button is turned OFF, the replication will stop.
      • When the button is set to the ON position, replication will start.
      • When replication is enabled, we instantiate the replicator config with the local database and provide centralized database details to indicate the source and target for push/pull replications.

Set up the event monitor for replication events:

In we also remove a lot of hardcoded values from the requests records, so we can showcase the records as they would look like for different users.

In the SENDDATA function, observe how hardcoded values are replaced by relevant input fields:

In the RECEIVEDATA function, we remove the extra write that previously emulated getting a rating request. This is defunct now that we added the USER input field that allows us to get the rating/requests back for the specific user.

In the INCOMINGRATINGS function, trim the code down to get requests based on username:


A few updates are made to the and files as well. For this iteration, we will remove a lot of hardcoded FROM and TO values because we want to showcase the app for two different users. This helps show how the bi-directional sync between the app and the server works.

Similar changes were made to remove hardcoded names and we carry forward the username and request details from the mainpage of the app.


Compiling the mobile application code 

Once all the code has been updated, click on Build → ReBuild Project, then Build → Run when the rebuild is complete.

You will be asked to choose the emulator the first time you run the app. I created the NEXUS 5X API 25 device and chose that when asked. 

Once the run is complete the main page will look like this:

Couchbase Mobile app with new UI components

You have now successfully deployed the code into the emulator of your choice.

A Quick Test 

Let’s create a rating request following these steps:

  1. Turn the SYNC switch on.
  2. Enter the rating request details (target user, message, subject).
  4. Go the Couchbase Server instance. In my case, it’s my local instance web console. Navigate to Buckets and Documents and you should see the rating request created on server.
  5. Now put in the user name AlPacino and click on RECEIVED RATING REQUESTS–you should see the rating request in the RECEIVED section ready to be rated. Rate this request.
  6. When you check the console you will see two JSON documents as shown below.

Updated mobile app UI

Observe the two records in the console.

Coucbase Server console showing JSON documents
Now let’s make a change to the rated request by AlPacino and change number of stars to 2 and see if the changes trickle down to the device.

Couchbase web console for viewing JSON document changes

Run the app and pull up INCOMING RATED REQUESTS (bottom of screen) for TomCruise and you will see the change to 2 stars.

Updated mobile app screenshot on Couchbase Mobile

Next steps

This is part 3 of the blog series Building A Mobile Application with Couchbase. This post showed how to enable device-to-server syncing.

In the next part of the series we show you how to enable peer-to-peer device syncing.

Continue learning by following these resources:


Posted by Sandhya Krishnamurthy, Senior Solutions Engineer, Couchbase

Sandhya Krishnamurthy is a technologist with a strong database development background and pre-sales experience. She is a part-time artist, part-time singer and full-time mom.

Leave a reply