Edit on GitHub

Add Couchbase Lite to your app


iOS & tvOS

  1. Download Couchbase Lite for the platform your app is targeting.
  2. Unzip the file.
  3. Open the Couchbase Lite folder and drag CouchbaseLite.framework to the project navigator in Xcode.
  4. In the Choose options for adding these files sheet, make sure that your app target is selected.

Couchbase Lite requires additional frameworks and libraries for building an app. These additional dependencies are added via Xcode build settings.

  1. In the Xcode navigator, click on the project open the Build Settings tab.
  2. Scroll to the Linking section, find the Other Linker Flags row and then add the flag -ObjC (be sure to use the capitalization shown).
  3. Click the Build Phases tab.
  4. Expand the Link Binary With Libraries section and add the following items.


    To use the SDK in Swift files, you must also import the framework in a bridging header (#import <CouchbaseLite/CouchbaseLite.h>).


For a macOS target, you'll need to make sure the framework is copied to your app's bundle. Follow the steps below.

  1. Download Couchbase Lite for the platform your app is targeting.
  2. Open the Build Settings tab of your app target's settings.
  3. In the Linking section, edit Runpath Search Paths and add @loader_path/../Frameworks/.
  4. Now switch to the Build Phases.
  5. Press the Add Build Phase button at the top of the window and create a new Copy Files phase.
  6. Set the phase's destination to Frameworks.
  7. Press the + button below the phases' file list and select CouchbaseLite.framework to add it.

Available frameworks

Framework Service
CouchbaseLiteListener.framework To access the database through HTTP (often used for hybrid development and peer-to-peer sync). This component has a dependency on JavaScriptCore.framework, make sure to add this framework as well if you're planning on using it.
CBLJSONValidator Validates JSON objects against JSON-Schema specs.
CBLRegisterJSViewCompiler, libCBLJSViewCompiler.a To register Views and Filters through the Listener. When doing so, the logic is written in JavaScript and stored in the database.
libCBLForestDBStorage.a To use ForestDB as the storage type.
libsqlcipher.a To enable encryption on SQLite databases.
Extras/CBLEncryptionController Utility class to handle password entry. Prompts the user to make up a key, asks for the key when re-opening the database, and asks again if the key was incorrect. It even takes advantage of Touch ID fingerprint authentication on recent iOS devices to avoid making the user deal with a password at all.
Extras/CBLIncrementalStore A subclass of the NSIncrementalStore to allow Core Data to use a Couchbase Lite database as its persistent storage instead of the default SQLite database.
Extras/CBLUICollectionSource A UICollectionView data source driven by a CBLLiveQuery.


  1. Install Cocoapods
  2. In your Podfile, add the following.

    pod 'couchbase-lite-ios', '~> 1.3.1'
  3. Install the pods and open the .xcworkspace file generated by Cocoapods.

    pod install

    To use the SDK in Swift files, you must also import the framework in a bridging header (#import <CouchbaseLite/CouchbaseLite.h>).

    The following subspecs are available to import different Couchbase Lite components.

    Pod Service
    couchbase-lite-ios/SQLite To use SQLite as the storage type. This is the default.
    couchbase-lite-ios/SQLCipher To use SQLCipher as the storage type.
    couchbase-lite-ios/ForestDB To use ForestDB as the storage type.


  1. Install Carthage
  2. Add github "couchbase/couchbase-lite-ios" "release/1.3.1" to your Cartfile.
  3. Run carthage update --platform ios.
  4. Drag CouchbaseLite.framework from the appropriate platform directory in Carthage/Build/ to the Embedded Binaries section of your Xcode project's General settings.

Getting Started

Create a new Xcode project and install Couchbase Lite by following one of the methods above.

Open ViewController.swift in Xcode.

If you installed Couchbase Lite with Carthage, append the following in your import section.

import CouchbaseLite

Then, add the following in the viewDidLoad method.

// Create a manager
let manager = CBLManager.sharedInstance()

let database: CBLDatabase
do {
 // Create or open the database named app
 database = try manager.databaseNamed("app")
} catch {
 print("Database creation or opening failed")

// The properties that will be saved on the document
let properties = ["title": "Couchbase Mobile", "sdk": "iOS"]
// Create a new document
let document: CBLDocument = database.createDocument()

do {
 // Save the document to the database
 try document.putProperties(properties)
} catch {
 print("Can't save document in database")

// Log the document ID (generated by the database)
// and properties
print("Document ID :: \(document.documentID)")
print("Learning \( "sdk")!)")

// Create replicators to push & pull changes to & from Sync Gateway
let url = URL(string: "http://localhost:4984/hello")!
let push = database.createPushReplication(url)
let pull = database.createPullReplication(url)
push.continuous = true
pull.continuous = true

// Start replicators

Build and run. You should see the document ID and property printed to the console. The document was successfully persisted to the database.

Before synchronizing documents to Sync Gateway you will need to disable App Transport Security. In the Xcode navigator, right-click on Info.plist and open it as a source file.

Append the following inside of the <dict> XML tags to disable ATS.


The application is now correctly configured to start synchronizing documents with Sync Gateway.

Installing Sync Gateway ⟶