Upgrade
|
On upgrading from a 2.x release, all Couchbase Lite databases automatically re-index on initial database open. |
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 getTimestamp() method 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 MessageEndpointListener.
Sync attempts with CBL 3.x peers fail with appropriate error messages.
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.
API Changes
This section introduces the changes made to the Couchbase Lite for Java API for release 4.0.0.
Removed
ResetCheckpoint
The method Replicator.resetCheckpoint() method has been removed.
Instead, use Replicator.resetCheckpoint(boolean reset).
replicator.resetCheckpoint()
replicator.start()replicator.start(true)Database.setLogLevel
The method Database.setLogLevel()
has been removed.
Instead:
-
Set the logging levels for loggers, individually
-
Explicitly set the domains that the console logger logs.
Database.setLogLevel(LogDomain.ALL, LogLevel.VERBOSE)Database.log.getConsole().setDomains(LogDomain.ALL_DOMAINS)
Database.log.getConsole().setLevel(LogLevel.VERBOSE)
Database.log.getFile().setDomains(LogLevel.DEBUG)Database.compact
The Database.compact() method has been removed.
It’s replaced by the new Database.performMaintenance(MaintenanceType) method, and the maintenance operations represented in the enum MaintenanceType
try testdb.compact()testdb.performMaintenance(MaintenanceType.COMPACT)Deprecated in the API
MATCH
The class, FullTextExpression
has been deprecated.
Use FullTextFunction instead.
FullTextExpression index = FullTextExpression.index("indexName")
Query q = QueryBuilder.select([SelectResult.expression(Meta.id)])
.from(DataSource.database(testdb))
.where(index.match(queryString))Query q = QueryBuilder.select([SelectResult.expression(Meta.id)])
.from(DataSource.database(testdb))
.where(FullTextFunction.match("indexName", queryString))isNullOrMissing/notNullOrMissing
The functions Expression.isNullOrMissing and Expression.notNullOrMissing have been deprecated.
Use isNotValued() and-or isValued() instead.
Query q =
QueryBuilder
.select([SelectResult.expression(Meta.id)])
.from(DataSource.database(testdb))
.where(
Expression.property("missingProp").isNullOrMissing())
Query q =
QueryBuilder
.select([SelectResult.expression(Meta.id)])
.from(DataSource.database(testdb))
.where(Expression.property("notMissingProp").notNullOrMissing())Query q = QueryBuilder.select([SelectResult.expression(Meta.id)])
.from(DataSource.database(testdb))
.where(Expression.property("missingProp").isNotValued())
Query q = QueryBuilder.select([SelectResult.expression(Meta.id)])
.from(DataSource.database(testdb))
.where(Expression.property("notMissingProp").isValued())AbstractReplicatorConfiguration
The enum AbstractReplicatorConfiguration.ReplicatorType
and the methods
ReplicatorConfiguration.setReplicatorType
and
ReplicatorConfiguration.getReplicatorType
have all been deprecated.
Instead, use the methods ReplicatorConfiguration.setType and ReplicatorConfiguration.getType, and the top level enum ReplicatorType.
ReplicatorConfiguration config =
new ReplicatorConfiguration().setReplicatorType(ReplicatorConfiguration.ReplicatorType.PUSH_AND_PULL);ReplicatorConfiguration config =
new ReplicatorConfiguration().setType(ReplicatorType.PUSH_AND_PULL);Moved in the API
The enum AbstractReplicator.ActivityLevel and the classes AbstractReplicator.Progress and AbstractReplicator.Status have all been moved to be top level definitions.
They are replaced by these definitions:
ListenerToken token =
replicator.addChangeListener(
testSerialExecutor,
change -> {
final AbstractReplicator.Status status = change.getStatus()
if (status.getActivityLevel() == AbstractReplicator.ActivityLevel.BUSY)
{ AbstractReplicator.Progress progress =
status.getProgress(); Logger.log("Progress: " + progress.completed + "/" progress.total);
}
});ListenerToken token =
replicator.addChangeListener(
testSerialExecutor,
change -> {
final ReplicatorStatus status = change.getStatus()
if (status.getActivityLevel() == ReplicatorActivityLevel.BUSY)
{ ReplicatorProgress progress =
status.getProgress(); Logger.log("Progress: " + progress.completed + "/" progress.total);
}
});Downgrading Couchbase Lite
Downgrading Between Major Releases
No Downgrade Support - Couchbase Lite (CBL) does not support downgrades between major versions. Upgrading to a new major version creates incompatibility issues when attempting to downgrade to a previous major version. 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.