Couchbase Lite for iOS keeps a core database and two product editions on separate release lines

The database itself lives in another repository

The first thing to understand about this repository is what it does not contain. The README states that the Couchbase Lite implementation for iOS sits on top of Couchbase Lite Core, which it describes as a new cross-platform implementation of database CRUD and query features, as well as document versioning.

So this is a platform binding, not an engine. The parsing, storage and query code is maintained elsewhere and reaches this repository as a vendored dependency, and the `vendor/` directory at the top level plus the `.gitmodules` file show how that vendoring is wired.

That division has a direct consequence for your upgrade planning. When you move to a newer Couchbase Lite for iOS, you are also taking whatever version of Lite Core the release pins, and the compatibility work happens upstream. If you are debugging a query that behaves unexpectedly, the bug is more likely in the core than in the Objective-C or Swift wrapper in this repository.

The repository also exists in two languages in one project. `Objective-C/` and `Swift/` are sibling directories, and the CocoaPods table lists four products across the two axes: the API you call and the edition you are licensed for.

Four pods because there are two axes of choice

The CocoaPods table is the clearest statement of the product structure in the README. There is an API choice, Objective-C or Swift, and an edition choice, Community or Enterprise, and the combinations are four distinct pods:

| API | Community Edition | Enterprise Edition | | --- | --- | --- | | Objective-C | `CouchbaseLite` | `CouchbaseLite-Enterprise` | | Swift | `CouchbaseLite-Swift` | `CouchbaseLite-Swift-Enterprise` |

So `CouchbaseLite` and `CouchbaseLite-Swift` are the same edition in two languages, and the Enterprise pair is the same edition in two languages. Picking the wrong cell is not a compile error you will discover late in an afternoon.

The Podfile itself is minimal, with a target block that enables frameworks and names the pod:

target '<your target name>' do
  use_frameworks!
  pod 'CouchbaseLite-Swift'
end

Note that the repository root carries two podspec files, `CouchbaseLite.podspec` and `CouchbaseLite-Swift.podspec`, which correspond to the Objective-C and Swift variants. The Enterprise pods are not in this repository at all.

Swift Package Manager is the recommended route, and the URLs differ by edition

The README is unambiguous that Swift Package Manager is the recommended installation method for new projects, and that CocoaPods remains supported.

The Community Edition dependency points at the public Swift wrapper repository:

dependencies: [
        .package(name: "CouchbaseLiteSwift",
                 url: "https://github.com/couchbase/couchbase-lite-swift.git", 
                 from: "4.0.0"),
    ],

The Enterprise Edition points somewhere else entirely, at a separate repository:

dependencies: [
        .package(name: "CouchbaseLiteSwift",
                 url: "https://github.com/couchbase/couchbase-lite-swift-ee.git", 
                 from: "4.0.0"),
    ],

Both declare a minimum of 4.0.0 and both use the same package name, `CouchbaseLiteSwift`. That is convenient when you swap editions, and it is also a trap: if both end up in your dependency graph, or if a transitive dependency pulls one in, the names collide and the resolution failure will not tell you which edition you got.

The practical takeaway is to add the URL for exactly one of these, deliberately, and to check the resolved package afterwards.

Building the XCFramework yourself, submodules included

If you are distributing the database as a binary inside a product that needs your own signing and packaging, the README documents building it. Clone and initialise submodules, which matters because the vendored core arrives that way:

$ git clone https://github.com/couchbase/couchbase-lite-ios.git
$ cd couchbase-lite-ios
$ git submodule update --init --recursive

Then run the build script, passing the API flavour and an output directory:

# For building the Swift XCFramework
$ ./Scripts/build_xcframework.sh -s CBL_Swift -o output

# For building the ObjC XCFramework
$ ./Scripts/build_xcframework.sh -s CBL_ObjC -o output

The two flags are `CBL_Swift` and `CBL_ObjC`, and the script lives at `Scripts/build_xcframework.sh`. An XCFramework is the Apple mechanism for shipping one binary that covers both device and simulator slices, and for Intel and Apple Silicon, so this step is what produces an artefact you can embed.

Note that the clone command has no `--recursive`; the submodules are initialised in a separate step. The supporting directories confirm the setup: `CouchbaseLite.xcodeproj/`, `xcconfigs/`, `Resources/`, `Tests/`, and a `Jenkinsfile` at the root for CI builds.

Two release lines are moving at once

The recent release list is unusual and needs reading carefully. Three tags appear: 3.4.2 dated 2026-09-16, 4.1.2 dated 2026-09-16, and 4.1.0 dated 2026-07-01.

Two versions on the same day, one in the 3.x line and one in the 4.x line. This is the normal shape for a product where the major line corresponds to an edition or licensing generation rather than only to API changes, and it means there is no single latest version to point at. The build script and the Swift package both use 4.0.0 as a floor, which tells you the 4.x line is where current work lands and the 3.x line is still receiving fixes.

Maintenance is current either way. The last push was on 2026-10-16, and the repository is not archived. There are agent instruction files at the root, `AGENTS.md` and `CLAUDE.md`, plus a `.travis.yml` and a Jenkinsfile, which is a mix of older and newer CI practice.

The licence is Apache 2.0, and the README states that like all Couchbase source code it is released under that licence. That is permissive, with the usual obligations around notice and patent grant.

Where the choice gets uncomfortable

Two things are worth weighing before you commit.

The first is the platform floor. The README requires Xcode 26.4 or later, iOS 15.0 or later, and macOS 13.0 or later. Xcode 26.4 is the binding constraint for a development team rather than for users, because it dictates which machine you can build on and which CI images you can use. If your organisation has not moved its build fleet to that Xcode, the upgrade is a separate project before you can even evaluate the database.

The second is what sync actually buys you. The description calls this a syncable database engine, and that is the reason most teams consider it: a local store that can later reconcile with a server. What the README does not document is the topology, the conflict resolution rules, or the operational cost of running the server side. Those are documented on docs.couchbase.com, not here. If your application needs offline-first behaviour with multi-device reconciliation, the sync semantics are the part you must evaluate carefully, and this repository will not answer them for you.

There is a narrower case too. If all you need is structured local persistence on Apple platforms and you are not planning to sync, an embedded document database is a large dependency with its own storage format, its own migration story and a commercial parent. That is not an argument against it, but it is an argument for checking whether you are choosing it for the sync or for the storage.

Editorial conclusion

Couchbase Lite fits an Apple-platform app that needs a local document store with the option to sync to Couchbase Server later, and that already accepts the Xcode 26.4 and iOS 15 minimums. Verify first which release line you want, because 3.4.2 and 4.1.2 were both published on 2026-09-16 and mixing the two across the CocoaPods and Swift Package routes would leave you with two APIs, then confirm your deployment target against the iOS 15 and macOS 13 floors before you wire it into an app that still supports older systems.

Frequently asked questions

Official sources

1. couchbase/couchbase-lite-ios on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases