This post discusses how to use Couchbase Lite as an embedded database to share data between your iOS App and iOS App Extension.  App Extensions implement a specific task or functionality that can be exposed to other apps on the device or to the Operating System. In this post, we will walk through an example of how a Today Extension can be used with a Couchbase Lite embedded database in standalone mode.

NOTE:  We will be discussing Couchbase Mobile v1.4 which is the current production release. But everything we discuss here applies to the newer Developer Preview version 2.0 of Couchbase Mobile


Apple supports many kinds of App Extensions , each of which enables functionality that is relevant to a particular subsystem on the device.  In this post, we will discuss how Couchbase Lite can be used with a Today Extension. This type of extension, also known as a “Widget”, appears in the Today view of the Notification Center and allows users get quick updates. You can learn more about how App Extensions work in the Apple Developer documents.

I’ll assume you’re familiar with developing iOS Apps in Swift and have a basic understanding of integrating Couchbase Lite into your iOS App. This Getting Started guide is a great place to begin.  If would like to read up more on Couchbase, refer to the resources at the end of this post.

Couchbase Lite

Couchbase Lite is an embedded database that runs on devices. It can be used in several deployment modes. It can be used as a standalone embedded database or it can be used in conjunction with a remote Sync Gateway that would allow it to sync data across devices. In this post, we will use Couchbase Lite in standalone deployment mode. In this post, we will not go over the details of integrating with Couchbase Lite. The Getting Started With Couchbase Lite blog is a good place to get started on that.

Demo App

  • Download the Demo Xcode project from the Github repo . We will use this app as an example in the rest of the blog.

  • Follow the instructions in the README file to install and run the app

This is a simple Task List app that allows users to add, edit, delete tasks. A user can mark tasks as completed. A Today Extension is bundled with the app that shows the top 2 tasks right in your notification center without the need to open the app. The user can mark tasks as completed right from the notification center.

All tasks are stored in a local Couchbase Lite database. This implies that the Container app and the extension will both need access to the database.

App Architecture

App Extensions are not standalone apps. They are bundled within an App, referred to as a “Container App”.  Although App Extensions are bundled in the Container app, they run independent of the Container App in a separate process . App Extensions are launched by other apps that need the extension’s functionality. The App that launches the App Extension is referred to as the “Host App“.  The extension’s UI is displayed in the context of the Host App.

Although the Container App and the corresponding extension are independent processes running in their own sandbox, they can share data through a Shared Container.

The Shared Container can be set up by registering a unique App Group and enabling it for for both the container app and the extension. You will learn about setting this up in the next section.

App Extension Architecture

Configuring App Groups

Refer to the Apple Developer Docs to learn more about configuring App Groups in your iOS app

Open the CBLiteApp.xcworkspace of the demo app project that you downloaded.

  • Open the “Capabilities” tab of CBLiteApp Container App target . You should see the App Group enabled.
Enabling App Group

Enabling App Group for App










  • Open the “Capabilities” tab of CBLiteTaskExtension target. You should see the same App Group, enabled.

Configuring App group in Extension










Enabling the App Group capabilities for a target adds it to the Entitlements files for the container app and it’s extension.

  • In addition , you will have to add the App Groups feature to your App Id registered in the Apple Developer Portal.
Configuring App Group for App in Apple Developer Portal

Configuring App Group for App in Apple Developer Portal


App Walkthrough

Build and Run the App by choosing the App Target “CBLiteApp”. Now switch to the Today view of the Notification Center

  • Add your new Extension Widget to the Today View as shown below


Add Today Widget

  • Switch to the App and add couple of tasks tapping on the “+” button. Switch to the corresponding Today widget. You will notice that the tasks that you added are displayed in the widget.

Add Task

  • Mark a task as “Completed” by tapping on the task. Now switch back to the Container app. You will notice the completion status of the tasks is updated to correspond to actions taken from the Today widget.

Today Extension Update Task


  • Similarly edits or delete a task in the Container app by swiping the task entry. Switch to the Today widget. You will see the updated task list.

Force Touch

  • If your device supports 3D Touch, you can do a force touch on the app icon on home screen to reveal the Top Tasks extension right there from the icon and you can interact with it. Pretty cool !

Force Touch

  • Finally, terminate the Container App. Switch to the Today Widget and update the Completed status of a task. Relaunch the app. The tasks will be listed with the updated status.

Container App Termination


Code Walkthrough

Tasks are stored in a local Couchbase Lite embedded database. This implies that both the container app and the Today Extension need access to the database. As discussed earlier, the way to share data between the container app and the extension is through the Shared Container. This implies that the Couchbase Lite database must be located in the Shared Container.

The code to enable this is straightforward.

Open the DatabaseManager.swift file.

The DatabaseManager is a singleton class that handles basic database management functions.

  • Locate appGroupContainerURL function

This function constructs the path to the shared container folder.

  1. Return the URL to the shared group container. Group containers are stored in ~/Library/Group Containers/<application-group-id>
  2. Create a folder named CBLite in the shared group container.
  • Locate configureCBManagerForSharedData function

  1. Create CBLManagerOptions options object with the appropriate file protections. A value of completeFileProtectionUnlessOpen implies that read/write access to the file is restricted unless file is open
  2. Initialize the CBLManager with the path to the shared container. When the database is created, it will be created in the shared container.That’s it! The Couchbase Lite database is now in the Shared Container that both the App and the Extension can read and write to.

What Next?

Explore the rest of the demo sample code to understand how documents are added, edited and deleted. Specifically look at the TaskPresenter.swift file. This is where all the interactions with the Couchbase Lite database is handled.

If you have any questions, feel free to reach out to me on Twitter. If you would like to suggest improvements, submit a pull request to the GitHub repo. You can learn more about integrating with Couchbase Lite in this Getting started with Couchbase Lite blog. The Couchbase Forums are another great place to post your questions.

While this post discusses the use of Couchbase Lite in standalone mode, stay tuned for an upcoming post that will enhance the capability to include synchronization with the cloud.


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