Developing Using Couchbase Mobile CE for Android


    This tutorial will guide you through creating an Android Mobile application with Couchbase Mobile. To achieve this, you will install two server-side components: Couchbase Server CE and the Sync Gateway, and develop a mobile application with Couchbase Lite that will synchronize your data with the cloud seamlessly.

    Tested for Ubuntu 18.04, Docker CE 19.03.5 and Android Studio 3.5


    Docker will be used extensively through this tutorial since most components can be easily deployed with it. Type the next command in your console to verify if you have it already installed.

    sudo docker -v
    Docker version 19.03.5, build 633a0ea838

    If it is, the output should be similar to that one, and you can start the next section. Otherwise, check their official documentation, which contains install guides for multiple OS.

    Couchbase Server Community Edition(CE)

    The first step will be to get your server up and running. Create a local docker network named "couchbase-net". Open a terminal window and run the following command.

    docker network create -d bridge couchbase-net

    Check that the network was created.

    docker network ls
    NETWORK ID          NAME                                      DRIVER              SCOPE
    d3a4d9d23eab        bridge                                    bridge              local
    8cc9b7774503        couchbase-net                             bridge              local

    Create a directory to store the server data.

    mkdir ~/Couchbase

    To run the Couchbase Server CE in a container, you will first get the docker image from Dockerhub. Open a new terminal window and run the following.

    docker pull couchbase:community

    Once the command has completed you can start the server with the following line.

    docker run -itd --name couchbase-server  --network couchbase-net -v ~/CouchBase/:/opt/couchbase/var -p 8091-8094:8091-8094 -p 11210:11210 couchbase:community

    You can view the logs at any time by running the following command.

    docker logs couchbase-server

    It may take a few seconds for the server to startup. Verify that the container is running with the following command.

    docker ps

    To connect to your server go to your browser and access the Web UI on port 8091. There you will see a login screen like this one.


    Select Setup New Cluster, and fill the fields according to the following picture. Take note of your username and password!


    Press Next: Accept Terms, make sure to read and accept the terms and conditions. Then press Configure Disk, Memory, Services, read the preselected options and finally press Save & Finish.

    At this point, you have the server running, but you don’t have any data yet. Couchbase Server CE includes three sample buckets to help you start testing the server. We will use the beer-sample bucket, which has two document types: beers and breweries.

    Beer documents contain core information about different beers, including the name, alcohol by volume ( abv ) and categorization data. The brewery record includes basic contact and address information for the brewery, and contains a spatial record consisting of the latitude and longitude of the brewery location. Individual beer documents are related to brewery documents using the brewery_id field, which holds the information about a specific brewery for the beer.

    To add this bucket, login to the server’s Web UI. In the left panel, select Buckets, and click on sample bucket on the right panel.

    sample bucket1

    Select "beer-sample" and click on Load Sample Data.

    sample bucket2

    The data will be loaded into the server. You can explore the data by going to Buckets on the left panel, and selecting Documents on the right side. The data will look like this.

    sample bucket loaded

    Sync Gateway

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

    For more information about the Sync Gateway, refer to the official page and this blog post, Sync Gateway via the Command Line.

    To run the Sync Gateway container, download the image first.

    docker pull couchbase/sync-gateway:2.6.1-community

    The Sync Gateway container requires the name and port of the Couchbase Server CE, which is already configured in the sync-gateway-config-beersampler.json file.

    "server": "http://couchbase-server:8091"

    And the username and password needed to access it.

    "username": "Administrator",
    "password": "your password",

    Now set the username and password for the users authorized to connect to your Sync Gateway. Replace 123456 with your preferred passwords.

        "admin": {"password": "123456", "admin_channels": ["*"]},
        "demo": {"password": "123456"},
        "tester": {"password": "123456"}

    Launch the Sync Gateway container with the following command. Make sure that you are in the same directory of the configuration file.

    docker run -p 4984-4985:4984-4985 --network couchbase-net --name sync-gateway -d -v `pwd`/sync-gateway-config-beersampler.json:/etc/sync_gateway/sync_gateway.json couchbase/sync-gateway:2.6.1-community -adminInterface :4985 /etc/sync_gateway/sync_gateway.json

    Verify that the container named "sync-gateway" is running with the following command in the terminal window.

    docker ps

    You can view the logs at any time by running the following command.

    docker logs sync-gateway

    Test the sync interface in your browser by accessing port 4984.

    You should receive a JSON response, like the following.

    {"couchdb":"Welcome","vendor":{"name":"Couchbase Sync Gateway","version":"2.6"},"version":"Couchbase Sync Gateway/2.6.1(1;4907fed) CE"}

    Couchbase Lite

    Couchbase Lite provides an embedded NoSQL database for mobile apps. Depending on the deployment, it can be used in any of the following modes, or a combination of them:

    • As a standalone embedded database within your mobile apps.

    • Enables mobile clients with a Sync Gateway to synchronize data between your mobile clients.

    • Enables clients with a Sync Gateway to sync data between mobile clients and the Couchbase Server CE, which can persist data in the cloud (public or private).

    In this tutorial we will implement an Android application, using the first and third mode.

    Android Application

    The Android application will rely on Couchbase Lite, which will work together with the Sync Gateway to persist your data in the Couchbase Server CE in the cloud, be it public or private.

    We will be developing an application using one of the example buckets comprised in the Couchbase Server CE, the beer-sample bucket.

    The application aim will be to serve as an input form for the database, so any user can include new breweries or beers. Also, the user will be able to search in the database for beers or breweries.


    To start using Couchbase Lite, download our Beer Sampler Project and open it with Android Studio.

    Include the Library

    The first step to include Couchbase Lite support within an Android app is to declare it as a dependency in app/build.gradle.

    dependencies {
        implementation 'com.couchbase.lite:couchbase-lite-android:2.6.0'

    After this step, all Couchbase Lite methods become available for the application.

    Local Embedded Database: Open and Read Data

    The second step is to implement a method for opening the database. As previously stated, two modes will be implemented: standalone database and database synced with the cloud. The first case will be covered with a guest user, who will be able to store, modify or delete beers. The second case will be covered with an authenticated "demo" user, whose credentials were defined in the Sync Gateway before.

    Database handling is defined in app/src/main/java/com/couchbasece/beersampler/utils/ All Log.i lines are for informative logging. These logs can be seen at the bottom of Android Studio while the application is running, in the Logcat tab. You can select the Logcat tab with the key combination Alt + 6 in Android Studio.

    public void OpenGuestDatabase() {
        Log.i("appBeerSampler","Opening Guest Database");
        DatabaseConfiguration config = new DatabaseConfiguration();
        config.setDirectory(String.format("%s/guest", appContext.getFilesDir()));
        Log.i("appBeerSampler","Database path: "+config.getDirectory());
        try {
            database = new Database("guest", config);
        } catch (CouchbaseLiteException e) {

    When the user opens the applications and hits Access as Guest, a special user and password are stored in the Shared Preferences of the application, and a method for opening a new local database is invoked. From this method, the previous function is called.

    public void fetchBeers() {
        Log.i("appBeerSampler", "Opening local DB as user Guest");
        DatabaseManager dbMgr = DatabaseManager.getSharedInstance();

    Then, a query gets executed to retrieve the beers stored in the local database. These methods are located in app/src/main/java/com/couchbasece/beersampler/

    Database database = DatabaseManager.getDatabase();
    Log.i("appBeerSampler", "Connected to database: "+database.getName().toString());
    Query searchQuery = QueryBuilder
    Log.i("appBeerSampler", "Query loaded");
    ResultSet rows = null;
    try {
        Log.i("appBeerSampler", "Ready to run query");
        rows = searchQuery.execute();

    All rows retrieved will be shown in the application, and also in the logs.

    Cloud Database: Open and Read Data

    This section will be covered with the "demo" user, which was previously defined in the file sync-gateway-config-beersampler.json. The startup sequence for the database will be a little different this time.

    buttonLogin.setOnClickListener(new View.OnClickListener() {
        public void onClick(View v) {
            String user = usernameInput.getText().toString();
            String passwd = passwordInput.getText().toString();
            // Stores username and password on Shared Preferences
            SharedPreferences sp=getActivity().getSharedPreferences("Login", MODE_PRIVATE);
            SharedPreferences.Editor Ed=sp.edit();
            Ed.putString("username", user);
            Ed.putString("password", passwd);
            DatabaseManager dbMgr = DatabaseManager.getSharedInstance();
            DatabaseManager.startPushAndPullReplicationForCurrentUser(user, passwd);
            Intent intent = new Intent(getActivity().getApplicationContext(), BrowseData.class);

    Notice the startPushAndPullReplicationForCurrentUser(user, passwd), this method takes care of the replication and is defined on the file When the user inserts a beer, it is reflected in the Couchbase Server CE, in the cloud, via the Sync Gateway. The gateway is defined in, with a hostname.

    public static String mSyncGatewayEndpoint = "ws://PUT-THE-GATEWAY-IP-HERE:4984/beer-sample";

    After this step, all operations are common for the embedded or the remote database.

    Insert a New Document

    To insert a new beer, the user should tap the button.


    That allows entering the data regarding the new beer.


    Please insert some beers, and take note of the names inserted, for instance, "Polar Dark".


    The code that inserts the data simply creates a new MutableDocument with a unique ID and invokes the save method.

    mutableCopy = new MutableDocument(Brewery+"-"+BeerName, properties);
    try {
        Log.i("appBeerSampler", "Ready to insert");;

    If you are logged in with the user "demo", then you should see the new beer uploaded in the Couchbase Server CE, via the Sync Gateway. Note the "Polar Blondie" and "Polar Dark" beers.

    web app1

    Update an Existing Document

    To update an existing document, tap on the document. In the dialog, the user updates any value. Behind the scene, the document retrieved is modified and inserted again with the same ID.

    public void onClick(View v) {
        Log.i("appBeerSampler", "Update a beer");
        // Retrieving beer data from the interface
        String Brewery = breweryInput.getText().toString();
        String BeerName = beerNameInput.getText().toString();
        String Category = categoryInput.getText().toString();
        String Style = styleInput.getText().toString();
        String ABV = abvInput.getText().toString();
        // Get the database in use
        Database database = DatabaseManager.getDatabase();
        // Filling the beer's data
        HashMap<String, Object> properties = new HashMap<>();
        properties.put("type", "beer");
        properties.put("name", BeerName);
        properties.put("brewery_id", Brewery);
        properties.put("category", Category);
        properties.put("style", Style);
        properties.put("abv", ABV);
        // Retrieves username and password from Shared Preferences
        SharedPreferences sp1= getSharedPreferences("Login", MODE_PRIVATE);
        String user = sp1.getString("username", null);
        String passwd = sp1.getString("password", null);
        if (user.equals("D3m0u53r") && passwd.equals("D3m0u53r")) {
            properties.put("username", "guest");
        } else {
            properties.put("username", user);
        MutableDocument mutableCopy = new MutableDocument(Brewery+"-"+BeerName, properties);
        try {
            Log.i("appBeerSampler", "Ready to insert");
            Log.i("appBeerSampler", "Inserted");
        } catch (CouchbaseLiteException e) {

    Next Steps

    We recommend you to follow our next tutorials, go to the Getting Started with Couchbase Community Edition page to find the full list.

    Also, you could review Couchbase Documentation to learn more about all sorts of topics.