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.0 Upgrade

      Couchbase Lite 4.0 introduces significant architectural changes, most notably the migration from revision trees to version vectors for document versioning.

      Major Changes in 4.0.0

      Version Vector Architecture: CBL 4.0.0 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 long value representing nanoseconds since the Unix epoch.

      Database Compatibility

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

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

      Synchronization Compatibility

      Sync Gateway Requirements: CBL 4.0.0 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.0 can only perform peer-to-peer synchronization with other CBL 4.x instances using either URLEndpointListener or URLMessageEndpointListener. Sync attempts with CBL 3.x peers fail with appropriate error messages.

      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.x to CBL 4.x.x does not allow you to revert to CBL 3.x.x.

      Downgrading Between Minor Releases

      Conditional Downgrade Support - Downgrade support for minor releases is considered on a case-by-case basis. 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 - Downgrades between patch releases are supported. Users can safely 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

      .