Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

Upgrade

    On upgrading from a 2.x release, all Couchbase Lite databases automatically re-index on initial database open.
    This can result in a delay before the database is usable.

    4.0.3 Upgrade

    Couchbase Lite 4.0 introduces significant architectural changes, most notably the migration from revision trees to version vectors for document versioning. This upgrade requires understanding of the compatibility requirements.

    The action takes place automatically and can lead to some delay in the database becoming available for use in your application.

    In addition, if you’re syncing with a 4.0.3 Sync Gateway, you should be aware of the significant configuration enhancements introduced and their effects. See Upgrading Sync Gateway for more details. This is a one-way conversion.

    Major Changes in 4.0.3

    Version Vector Architecture: CBL 4.0.3 replaces the revision tree system with version vectors, providing improved performance, scalability, and conflict resolution. Documents now use version-based revision IDs in the format <timestamp>@<source-id> instead of the previous <generation>-<document-hash> format.

    Enhanced Conflict Resolution: The default conflict resolution strategy changes from most active wins to last write wins based on hybrid logical timestamps, providing more intuitive and predictable conflict resolution behavior.

    New Document Properties: a new timestamp property is available on Document objects, providing direct access to the document’s logical timestamp as a UInt64 value representing nanoseconds since the Unix epoch.

    Database Compatibility

    Automatic Upgrade from 3.x: CBL 4.0.3 databases are compatible with CBL 3.1 and 3.2 databases. When opening a 3.1 or 3.2 database with CBL 4.0.3, documents are automatically upgraded to use version vectors when they’re updated and saved.

    No Configuration Required: CBL 4.0.3 enables version vectors by default - the feature requires no API configuration.

    Synchronization Compatibility

    Sync Gateway Requirements: CBL 4.0.3 requires Sync Gateway 4.x or later for synchronization. Attempting to sync with Sync Gateway versions prior to 4.x results in replication errors with appropriate error messages indicating the incompatibility.

    Peer-to-Peer Compatibility: CBL 4.0.3 can only perform peer-to-peer synchronization with other CBL 4.x instances using either URLEndpointListener or MessageEndpointListener. Sync attempts with CBL 3.x peers fail with appropriate error messages.

    API Changes

    Removed APIs

    ResetCheckpoint
    Alternative
    `replicator.start(reset:)`
    Before
    replicator.resetCheckpoint()
replicator.start()
    After
    replicator.start(true)
    Database.setLogLevel
    Alternative

    Database.log.console

    Before
    Database.setLogLevel(.verbose, domain: .all)
    After
    Database.log.console.domain = .all
Database.log.console.level = .verbose
    Database.compact
    Alternative

    Database.performMaintenance(type:)

    Before
    try testdb.compact()
    After
    try testdb.performMaintenance(type: .compact)

    Deprecated API

    Match
    Alternative

    FullTextFunction.match(indexName:)

    Before
    let index = FullTextExpression.index ("indexName")
let q = QueryBuilder.select([SelectResult.
expression(Meta.id)])
  .from(DataSource.database(testdb)) +
  .where(index.match("'queryString'"))
    After
    let q = QueryBuilder.select([SelectResult.expression(Meta.id)])
  .from(DataSource.database(testdb))
  .where(FullTextFunction.match(indexName: "indexName", query: "'queryString'"))
    isNullOrMissing and notNullOrMissing
    Alternatives

    isNotValued()
    isValued()

    Before
    |let q1 = QueryBuilder.select([SelectResult.expression(Meta.id)])
  .from(DataSource.database(testdb))
  .where(Expression.property("missingProp").isNullOrMissing())

let q2 = QueryBuilder.select([SelectResult.expression(Meta.id)])
  .from(DataSource.database(testdb))
  .where(Expression.property("notMissingProp").notNullOrMissing())
    After
    let q1 = QueryBuilder.select([SelectResult.expression(Meta.id)])
  .from(DataSource.database(testdb))
  .where(Expression.property("missingProp").isNotValued())

let q2 = QueryBuilder.select([SelectResult.expression(Meta.id)])
  .from(DataSource.database(testdb))
  .where(Expression.property("notMissingProp").isValued())

    Updated API

    Configuration

    The following classes are changed to Swift struct.

    • DatabaseConfiguration

    • ReplicatorConfiguration

    • URLEndpointListenerConfiguration

    Before
    let config = DatabaseConfiguration()
config.encryptionKey = EncryptionKey.password(password!)

let config = ReplicatorConfiguration(database: db, target: target)
config.continuous = true
    After
    var config = DatabaseConfiguration()
config.encryptionKey = EncryptionKey.password(password!)

var config = ReplicatorConfiguration(database: db, target: target)
config.continuous = true
    ATAN2
    Breaking change

    ATAN2(x, y) now becomes ATAN2(y, x)

    Before
    let p = Expression.property("number")
let q = QueryBuilder.select([SelectResult.expression(Function.atan2(x: Expression.int(90), y: p))])
  .from(DataSource.database(testdb))
    After
    let q = QueryBuilder.select([SelectResult.expression(Function.atan2(y: Expression.int(90), x: p))])
  .from(DataSource.database(testdb))

    Replication Compatibility

    CBL 4.0 introduces strict replication compatibility requirements due to the version vector architecture changes.

    Sync Gateway Compatibility: CBL 4.0 requires Sync Gateway 4.0 or later for synchronization. Attempting to sync with Sync Gateway versions prior to 4.0 results in replication errors with appropriate error messages indicating the incompatibility.

    Peer-to-Peer Compatibility: CBL 4.0 can only perform peer-to-peer synchronization with other CBL 4.0+ instances. Sync attempts with CBL 3.x or earlier peers fails with appropriate error messages.

    No Backward Compatibility: unlike previous CBL versions, CBL 4.0 cannot sync with earlier versions of either Sync Gateway or other CBL instances due to the fundamental changes in document versioning architecture.

    Xcode

    The API has changed in Couchbase Lite 2.0 and requires porting an application that’s using Couchbase Lite 1.x API to the Couchbase Lite 2.0 API. To update an Xcode project built with Couchbase Lite 1.x:

    • Remove the existing CouchbaseLite.framework dependency from the Xcode project.

    • Remove all the Couchbase Lite 1.x dependencies (see the 1.x installation guide).

    • Install the Couchbase Lite 2.0 framework in your project  — see Install. At this point, there are compiler warnings due to API changes. See the examples on this page to learn about the new API.

    • Build & run your application.

    Downgrading Couchbase Lite

    Downgrading Between Major Releases

    No Downgrade Support - Couchbase Lite (CBL) does not support downgrades between major versions. Once you upgrade to a new major version, attempting to downgrade to a previous major version creates incompatibility issues. For example, upgrading from CBL 3.x to CBL 4.x does not allow you to revert to CBL 3.x.

    Downgrading Between Minor Releases

    Conditional Downgrade Support - Downgrades receive evaluation on a case-by-case basis for minor releases. The release notes for each minor version clarify whether downgrades receive support.

    For example, when a new minor version such as CBL 3.1.0 becomes available, the release notes specify whether reverting to CBL 3.0.x receives support.

    Downgrading Between Patch Releases

    Full Downgrade Support - Couchbase Lite supports downgrades between patch releases. Users can downgrade between different patch versions within the same minor release.

    For example, if you’re running CBL 3.1.6 you can downgrade to CBL 3.1.4 or CBL 3.1.3 without issues.

    Related Content

    How to

    .

    Learn more

    .

    Dive Deeper

    Mobile Forum | Blog | Tutorials

    .