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 an 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.
Looking for Part 1? Head on over here and check it out!.
Pattern 1: Keeping the Data Up-to-Sync While the App Is in the Background
Backgrounding support on mobile apps varies drastically by the 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 the 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.
- 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
- Continuous replications are transitioned to offline mode when the app is pushed to the 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 the 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.
- There are a couple of options available if apps have to be run tasks in the background
- Continuous replications are not transitioned to offline mode when an app is pushed to the background. It is recommended however that apps close replicators when they transition to the background.
- Use raw notifications sent via Windows Push Notification Service(WPNS) to wake up the app while in the background
- When the 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 the local client store after it’s been synced over to the server for governance compliance reasons or to avoid local database bloat.
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.
- Model your documents to include a user-defined property that specifies the UTC time when the document expires. Let's call it validUntil.
- Register Replication Event observer on client Replicator
- On receiving
Pullevent 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 the 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).
- 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 synced
- 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 the 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 go with the most relevant document changes as soon as it has pulled them without having to wait 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.
- Assign documents to different channels based on priority. For instance, you could have documents assigned to “low”, “medium” or “high” priority channels.
- On the client-side, on initial launch, do a one-shot pull replication of the 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 the 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.