Since the first official release in 2014, Couchbase Mobile has enabled a wide variety of use cases of varying degrees of scale and complexity. Despite the variation, there are some common usage patterns for using Couchbase Mobile.

I have put together a series of blog posts that cover some common usage patterns and tips and recommended practices for addressing these use cases. In this blog post, we discuss common patterns if you are developing apps with Couchbase Lite. This post assumes that you are familiar with the fundamentals of Couchbase Mobile. If you need a primer, check out the docs on Couchbase Lite.

Pattern 1: Handling large volume of public, non-user specific data

Couchbase Mobile pattern for preloading couchbase lite data

With Couchbase Lite’s support for pre-built databases, you can preload the app with data instead of syncing it down from Sync Gateway during startup.

Use Case

Avoiding the initial sync will help reduce startup time and network transfer costs. This would typically apply to public/shared, non-user specific data that’s mostly static. Even if the data is not static, you can still avail the benefits of preloading the data and only syncing down the changes on startup.


    • Create an unencrypted copy of the .cblite database with the relevant data. There are two options to create a .cblite
      • Use a Couchbase Lite based app to pull relevant data via Sync Gateway. This will create an instance of a cblite file (with .cblite2 extension). The location of the generated file is platform specific and can be obtained from the DatabaseConfiguration object.
      • Use the open source, couchbaselabs cblite tool. This tool allows you to load data from a variety of sources.
    • Load the .cblite into the app in two ways. You have two options
      • The first option is to bundle the .cblite2 file with the app.
      • The second option is to host the .cblite file in a CDN from where it can be retrieved by the clients on startup. While there is still the cost of downloading the database file, there will still be considerable savings in bandwidth and latency costs by delivering it from a CDN.
    • Once loaded, follow the steps to copy() the bundled .cblite2 file into the app. This will create an instance of the database unique to the client

Pattern 2: Segregating client-local and synced data

Couchbase mobile pattern for local only data

You can support multiple instances of Couchbase Lite within your app. While are are no hard limits to the number of database instances, there are practical limits and restrictions, for instance, you cannot do cross-database joins.

Use Case

A common use case of having multiple databases within the app is to segregate the data that’s local only to the client into a separate database instance away from the rest of the data. There are other ways to enforce local-only constraints as we shall see in a separate pattern discussed later. However, segregating data would allow apps to enforce access control at the database level, ensure that queries and database operations are scoped to the database level. For instance, you can delete the local-only database without affecting the rest of the synced data.


    • Create an instance of Couchbase Lite database for local-only data. The database can be created or copied over from a bundled copy of pre-built database
    • Do not configure any replicators for the local-only database

Pattern 3: Supporting multi-user app

Couchbase Mobile pattern share database with multiple users

Couchbase Lite powered apps can support multiple users. This is another pattern that’s enabled with the ability to support multiple instances of Couchbase Lite within your app. Multi-user apps impose stringent requirements on data segregation and data access control to ensure that users don’t deliberately or inadvertently access or stomp on each other’s data.

Use Case

Multi-user apps are common, especially in scenarios where devices are shared.


    • Create a separate instance of Couchbase Lite database for each user
    • While not required, every instance of the database can be in a user specific folder, the location of which can be specified via the DatabaseConfiguration at the time of database creation. If desired, each Couchbase Lite database can be encrypted using user specific password/key.
    • Common data shared between the users can be stored in a shared instance of database in a “common” folder
    • When switching between users or “logging off”, ensure the following

Pattern 4: Sharing data between apps on a device

Couchbase Mobile pattern share database between apps

Mobile apps run in a sandboxed environment. So a given app only has access to or can only modify it’s own data. However on certain platforms, options exist that facilitate sharing of resources between apps with the right entitlements. Using such mechanisms that are specified by the platform, an instance of Couchbase Lite database can be shared by multiple apps. This is in accordance with the guidelines prescribed by the platform.

Configuration Implication
All Readers, no Writers OK
Single Writer, multiple Readers OK – no inter-process change notifications
Multiple Writers Untested. Database will be locked with multiple concurrent accesses (YMMW*)

Use Case

Multiple apps from the same vendor could be working off of the same data. Instead of having each app maintain an identical copy of the data, sharing the database will reduce transfer costs as well as local storage costs on the device.


    • The idea is to host the database in a folder or location on filesystem that is accessible to the apps that are sharing it. Configuring the apps to share data is a platform-level implementation
      • On iOS, you would use App Groups similar to what is described in this blog to set up access to shared Couchbase Lite resource from multiple apps.
      • On Android, you could leverage Content Providers to enable sharing of Couchbase Lite data between apps

What Next

In this post, we covered a few common usage patterns in Couchbase Lite. We will continue to publish posts describing other tips and recommendations for solving common problems.
If you have questions or feedback, please leave a comment below or feel free to reach out to me at Twitter @rajagp or email me  The Couchbase Forums are another good place to reach out with questions.


I would like to acknowledge the contributions of the Couchbase Lite development team, specifically Jim Borden for his review of this blog post.


Posted by Priya Rajagopal, Senior Director, Product Management

Priya Rajagopal is a Senior Director of Product Management at Couchbase responsible for developer platforms for the cloud and the edge. She has been professionally developing software for over 20 years in several technical and product leadership positions, with 10+ years focused on mobile technologies. As a TISPAN IPTV standards delegate, she was a key contributor to the IPTV standards specifications. She has 22 patents in the areas of networking and platform security.

Leave a reply