Skip to content

DOC-14095 upgrade instructions #1081

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
iamfortune wants to merge 3 commits into
base: release/4.1
Choose a base branch
from
Open

DOC-14095 upgrade instructions #1081

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
205b260
update infra version
iamfortune Mar 12, 2026
aeb5b90
update the upgrade to show new version
iamfortune Mar 16, 2026
80faf07
Merge branch 'release/4.1' into DOC-14095-upgrade-instructions
iamfortune Apr 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 15 additions & 15 deletions antora.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
name: couchbase-lite
version: '4.0'
prerelease:
version: '4.1'
prerelease: true
title: Couchbase Lite
start_page: ROOT:index.adoc
nav:
Expand All @@ -14,21 +14,21 @@ nav:
- modules/swift/nav-swift.adoc
asciidoc:
attributes:
prerelease:
previous-release:
release: '4.0'
prerelease: true
previous-release:
release: '4.1'
# releasetag:
major: 4
major-net: 4
minor: 0
minor-net: 0
maintenance-ios: 3
maintenance-c: 3
maintenance-android: 3
maintenance-java: 3
maintenance-net: 3
maintenance-swift: 3
base: 3
minor: 1
minor-net: 1
maintenance-ios: 0
maintenance-c: 0
maintenance-android: 0
maintenance-java: 0
maintenance-net: 0
maintenance-swift: 0
base: 0

# Used for Vector Search Extension.
vs-major: 2
Expand All @@ -41,4 +41,4 @@ asciidoc:
vs-maintenance-net: 0

page-toclevels: 2@
# NB: `preview` config now in preview/HEAD.yml, please update
# NB: `preview` config now in preview/HEAD.yml, please update
71 changes: 47 additions & 24 deletions modules/android/pages/upgrade.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,62 +1,89 @@

= Upgrade
:page-aliases: advance/java-android-dep-upgrade.adoc, dep-upgrade.adoc
:page-role:


:source-language: Java


:source-language: Kotlin


// The admonition does not apply to C as it references upgrading from versions 2.x.
// CBL-C started at version 3.0
[IMPORTANT]
--
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]
[#4-1-0-upgrade]
== {major}.{minor}.{base}{empty} Upgrade

Couchbase Lite 4.0 introduces significant architectural changes, most notably the migration from revision trees to version vectors for document versioning.
Couchbase Lite {major}.{minor} is a non-breaking upgrade from 4.0.
Update your Couchbase Lite dependency to {major}.{minor} -- no API or configuration changes are required.
Existing `MultipeerReplicatorConfiguration` setups continue to work without modification.
The default transport remains Wi-Fi only.

=== Enabling Bluetooth Transport (Optional)

To enable Bluetooth Low Energy transport alongside Wi-Fi, set the `transports` property on your `MultipeerReplicatorConfiguration`:

[source, Kotlin]
----
val config = MultipeerReplicatorConfiguration(
peerGroupID = "myGroup",
identity = identity,
authenticator = authenticator,
collections = collections)
config.transports = EnumSet.of(MultipeerTransport.WIFI, MultipeerTransport.BLUETOOTH)
----

[source, Java]
----
MultipeerReplicatorConfiguration config = new MultipeerReplicatorConfiguration(
"myGroup",
identity,
authenticator,
collections);
config.setTransports(EnumSet.of(MultipeerTransport.WIFI, MultipeerTransport.BLUETOOTH));
----

Bluetooth transport requires Android API 29 or later.
For full configuration options, see xref:android:p2psync-multipeer-transports.adoc[Configure Transports].

[#4-0-0-upgrade]
== 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 {major}.{minor}.{base}{empty}
=== Major Changes in 4.0.0

**Version Vector Architecture**:
CBL {major}.{minor}.{base}{empty} replaces the revision tree system with version vectors, providing improved performance, scalability, and conflict resolution.
CBL 4.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-40]
=== Database Compatibility

**Automatic Upgrade from 3.x**:
CBL {major}.{minor}.{base}{empty} databases are compatible with CBL 3.1 and 3.2 databases.
When opening a 3.1 or 3.2 database with CBL {major}.{minor}.{base}{empty}, documents are automatically upgraded to use version vectors when they're updated and saved.
CBL 4.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, documents are automatically upgraded to use version vectors when they're updated and saved.

**No Configuration Required**:
CBL {major}.{minor}.{base}{empty} enables version vectors by default - the feature requires no API configuration.
CBL 4.0 enables version vectors by default - the feature requires no API configuration.

[#synchronization-compatibility-40]
=== Synchronization Compatibility

**Sync Gateway Requirements**:
CBL {major}.{minor}.{base}{empty} requires Sync Gateway 4.x or later for synchronization.
CBL 4.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 {major}.{minor}.{base}{empty} can only perform peer-to-peer synchronization with other CBL 4.x instances using either `URLEndpointListener` or `URLMessageEndpointListener`.
**Peer-to-Peer Compatibility**: CBL 4.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 Couchbase Lite

Expand All @@ -83,10 +110,8 @@ Users can safely downgrade between different patch versions within the same mino

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.


// Include standard footer


[#related-content]
== Related Content
++++
Expand All @@ -100,7 +125,6 @@ For example, if you're running CBL 3.1.6 you can downgrade to CBL 3.1.4 or CBL 3
* xref:android:gs-install.adoc[Install]
* xref:android:gs-build.adoc[Build and Run]


.

[.column]
Expand All @@ -111,21 +135,20 @@ For example, if you're running CBL 3.1.6 you can downgrade to CBL 3.1.4 or CBL 3
* xref:android:blob.adoc[Blobs]
* xref:android:replication.adoc[Remote Sync Gateway]
* xref:android:conflict.adoc[Handling Data Conflicts]
// TODO: Uncomment when DOC-14098 pages are merged
// * xref:android:p2psync-multipeer-transports.adoc[Configure Transports]

.


[.column]
=== {empty}
.Dive Deeper
.Dive Deeper
https://forums.couchbase.com/c/mobile/14[Mobile Forum] |
https://blog.couchbase.com/[Blog] |
https://docs.couchbase.com/tutorials/[Tutorials]

.


++++
</div>
++++

++++
32 changes: 15 additions & 17 deletions modules/c/pages/upgrade.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,41 +2,40 @@
:page-aliases:
:page-role:


:source-language: c

:url-api-references-classes: https://docs.couchbase.com/mobile/{major}.{minor}.{maintenance-c}{empty}/couchbase-lite-c/C/html/group__


// The admonition does not apply to C as it references upgrading from versions 2.x.
// CBL-C started at version 3.0

[IMPORTANT]
--
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]
[#4-1-0-upgrade]
== {major}.{minor}.{base}{empty} Upgrade

Couchbase Lite {major}.{minor} is a non-breaking upgrade from 4.0.
Update your Couchbase Lite dependency to {major}.{minor} -- no API or configuration changes are required.

[#4-0-0-upgrade]
== 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.
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 {major}.{minor}.{base}{empty} Sync Gateway, you should be aware of the significant configuration enhancements introduced and their effects.
In addition, if you're syncing with a 4.0 Sync Gateway, you should be aware of the significant configuration enhancements introduced and their effects.
See xref:sync-gateway::upgrading.adoc[Upgrading Sync Gateway] for more details.
This is a one-way conversion.

// All API and other listed changes included in the other platforms do not apply to CBL-C for the following reasons
// The changes apply to pre 3.x versions (CBL-C started at 3.0)
// Or they relate to Querybuilder functionality - CBL-C doesn't have Querybuilder.

=== Major Changes in {major}.{minor}.{base}{empty}
=== Major Changes in 4.0.0

**Version Vector Architecture**:
CBL {major}.{minor}.{base}{empty} replaces the revision tree system with version vectors, providing improved performance, scalability, and conflict resolution.
CBL 4.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.
Expand All @@ -48,20 +47,20 @@ Access to document timestamps is available through the `c4rev_getTimestamp()` fu
=== Database Compatibility

**Automatic Upgrade from 3.x**:
CBL {major}.{minor}.{base}{empty} databases are compatible with CBL 3.1 and 3.2 databases.
When opening a 3.1 or 3.2 database with CBL {major}.{minor}.{base}{empty}, documents are automatically upgraded to use version vectors when they're updated and saved.
CBL 4.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, documents are automatically upgraded to use version vectors when they're updated and saved.

**No Configuration Required**:
CBL {major}.{minor}.{base}{empty} enables version vectors by default - the feature requires no API configuration.
CBL 4.0 enables version vectors by default - the feature requires no API configuration.

[#synchronization-compatibility-40]
=== Synchronization Compatibility

**Sync Gateway Requirements**:
CBL {major}.{minor}.{base}{empty} requires Sync Gateway 4.x or later for synchronization.
CBL 4.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 {major}.{minor}.{base}{empty} can only perform peer-to-peer synchronization with other CBL 4.x instances using either `CBLURLEndpointListener` or `CBLMessageEndpointListener`.
**Peer-to-Peer Compatibility**: CBL 4.0 can only perform peer-to-peer synchronization with other CBL 4.x instances using either `CBLURLEndpointListener` or `CBLMessageEndpointListener`.
Sync attempts with CBL 3.x peers fail with appropriate error messages.

[#replication-compatibility]
Expand Down Expand Up @@ -103,7 +102,6 @@ Users can downgrade between different patch versions within the same minor relea

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.

// Include standard footer

[#related-content]
== Related Content
Expand Down
3 changes: 0 additions & 3 deletions modules/csharp/pages/upgrade.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,9 @@
:page-aliases: advance/csharp-dep-upgrade.adoc, dep-upgrade.adoc
:page-role:


:source-language: c#


// The admonition does not apply to C as it references upgrading from versions 2.x.
// CBL-C started at version 3.0
[IMPORTANT]
--
On upgrading from a 3.x release, all Couchbase Lite databases automatically re-index on initial database open. +
Expand Down
Loading
Loading