Best Practices and Patterns with Couchbase Mobile – Part 2

Couchbase Mobile enables a wide range of offline-first use cases of varying degrees of scale and complexity. In an earlier post, I discussed common patterns while using Couchbase Lite as embedded NoSQL data store within your apps. Those patterns focused on local data storage. In this blog post, we discuss a few common patterns and best practices as it relates to syncing data with the Sync Gateway. 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 and Sync Gateway.

Pattern 1: Keeping the data up-to-sync while app is in the background

Backgrounding support on mobile apps varies drastically by platform. In fact, on certain platforms such as Android, the concept of “backgrounded apps” is quite nebulous/complicated. So how you would sync data while your app is in the background is very much platform-dependent. You can find a discussion on how Couchbase Lite reacts to app life cycle on iOS, Android and Windows in our documentation.

• Use Case

By keeping the data up-to-date when not in active use (or in the foreground), apps can improve end-user experience by reducing start up time on subsequent launches.

• Approach
  • It should be noted that there is no guarantee that your app will be permitted to run in the background. That is typically a system level or a user level decision.
  • How an app handles background sync is platform dependent
  • It is generally recommended that when possible, your app react to suitable app life cycle events and close the replicator before transitioning to the background
  • iOS
    • Continuous replications is transitioned to offline mode when app is pushed to background
    • Use Apple Push Notification Sevice (APNS) to send a silent notification to wake up the app while in the background or use Background App Refresh to let the system opportunistically wake up the app
    • When app is woken up in the background, do a one-shot replication to sync data
    • More on background support on iOS in this blog post.
  • Android
    • There are couple of options available if apps have to be run tasks in the background
      • Use Foreground Service for long running replications in the background
      • Use Work Manager to schedule one-shot replications to run asynchronously in the background or use Remote Firebase Cloud Messaging(FCM) to kick off a work request to run a one-shot replication
  • UWP
    • Continuous replications are not transitioned to offline mode when an app is pushed to background. It is recommended however that apps close replicator when they transition to background
    • Use raw notifications sent via Windows Push Notification Service(WPNS) to wake up the app while in the background
    • When app is woken up in the background, schedule a background task to do a one-shot replication to sync data

Pattern 2: Purge after Push

Couchbase Lite supports the ability for apps to be notified on the replication status of a document or set of documents via Replication Eventing capability. Apps can leverage this capability to take appropriate action on the document depending on the status such as purging the document.

• Use Case

It may be desirable to remove documents from local client store after it’s been synced over to the server for governance compliance reasons or to avoid local database bloat.

• Approach
  • Register Replication Event observer on Replicator
  • On receiving onPushed event on document(s), invoke purge() API to get rid of document. Purged documents are not synced.

Pattern 3: Enforcing server side document lifespan on disconnected clients

Couchbase Lite supports the ability for apps to set expiration dates on local documents via Expiration Date feature. Apps can leverage this capability to locally expire a document on Couchbase Lite regardless of connectivity to the server.

• Use Case

Documents created on the server may be associated with a TTL or expiration date that dictates when the document has to be purged from the system (clients and server). When there is network connectivity, documents deleted on the server side will be synced over to the client side so they are deleted on client side as well. However, it is likely that clients are offline when documents expire on the server and it may be important that these documents be removed from the clients in a timely fashion.

• Approach
  • Model your documents to include a user-defined property that specifies the UTC time when document expires. Lets call it validUntil.
  • Register Replication Event observer on client Replicator
  • On receiving Pull event on document(s), use the validUntil value to set the TTL on documents using the setExpirationDate() API
  • When documents expire on the client, they are automatically purged from the client regardless of network connectivity. The purged documents are not synced.
  • On the server side, the documents can be purged independently
  • Caveat : If the expirationDate(as defined by validUntil property)is updated while the clients are offline, then the clients will not be notified of this change. So it is possible that documents may get prematurely purged on clients when they are offline. So this approach is safe as long as the lifespan of document does not change after creation. We will discuss another approach to handle such cases.

Pattern 4: Controlling when and what documents get synced to server

Couchbase Lite supports the ability for apps to set fine-grained filters on the replicator that determines what documents get pushed to the server. This capability can be leveraged to control when and what documents get synced to the server.

• Use Case

In an earlier blog, we discussed how a separate instance of a database can be used for holding local-only data. While that pattern works when you need strict data segregation and if cross-database join queries are not required, there are use cases when you would want fine-grained control over when the local changes are to be synced. You could also use this pattern as an alternative to the pre-built database pattern in order to enforce that documents are local-only( i.e. never synced).

• Approach
  • Model your documents to include a user-defined “status” property that controls the business workflow. For instance, use a value of “in-progress” to indicate when changes are not ready to be synced and a status value of “committed” when changes need to be pushed up. If you need to make documents local-only, then use a user-defined “scope” property with a value of “local” to indicate that documents are not to be syned
  • Configure suitable Replication Filter function on the replicator. The filter should inspect the document property (as defined above) to determine if a document needs to be synced or not
  • Every time there are changes ready to be pushed, the filter function is applied by the Couchbase Lite replicator and documents are synced only if the filter criteria is satisfied.

Pattern 5: Controlling the priority order of initial set of documents synced to the client

Sync Gateway channels allow apps to segregate data based on type, purpose, access control permissions etc. This can be leveraged to segregate data based on priority.

• Use Case

The ability to prioritize the documents received by clients would ensure that the clients can get up and going with the most relevant document changes as soon as it has pulled them without having to waiting for the rest of the documents to sync. The remaining, lower priority document changes are pulled down later. This reduces the app response times on initial startup.

• Approach
  • Assign documents to different channels based on priority. For instance, you could have documents assigned to “low”, “medium” or “high” priority channels.
  • On client side, on initial launch, do a one-shot pull replication of highest priority channel by specifying the channels filter. Once the sync of the documents in channel completes, the app can kick off another replication for the remaining channels.
  • You can also set up a continuous replicator for highest priority channel and pull the remaining channels only on-demand using one-shot replication. This will ensure that the highest priority channel is kept up-to-sync in real time.

What Next

In this post, we covered a few common usage patterns in Couchbase Lite as it related to syncing data to and from the Sync Gateway and Couchbase server. We will continue to publish posts describing other tips and recommendations for solving common use cases.
If you have questions or feedback, please leave a comment below or feel free to reach out to me on Twitter or email me .  The Couchbase Forums are another good place to reach out with questions.

Acknowledgments

I would like to acknowledge the contributions of the Couchbase Lite and Sync Gateway development team, specifically Adam Fraser and Jim Borden for their review of the blog post.