Database Upgrade

    Databases created using Couchbase Lite 1.2 or later can still be used with Couchbase Lite 2.x; but will be automatically updated to the current 2.x version. This feature is only available for the default storage type (i.e., not a ForestDB database). Additionally, the automatic migration feature does not support encrypted databases, so if the 1.x database is encrypted you will first need to disable encryption using the Couchbase Lite 1.x API (see the 1.x Database Guide).

    Handling of Existing Conflicts

    If there are existing conflicts in the 1.x database, the automatic upgrade process copies the default winning revision to the new database and does NOT copy any conflicting revisions. This functionality is related to the way conflicts are now being handled in Couchbase Lite — see Handling Data Conflicts. Optionally, existing conflicts in the 1.x database can be resolved with the 1.x API prior to the database being upgraded.

    Handling of Existing Attachments

    Attachments persisted in a 1.x database are copied to the new database. NOTE: The relevant Couchbase Lite API is now called the Blob API not the Attachments API.

    The functionally is identical but the internal schema for attachments has changed. Blobs are stored anywhere in the document, just like other value types, whereas in 1.x they were stored under the _attachments field. The automatic upgrade functionality does not update the internal schema for attachments, so they remain accessible under the _attachments field. The following example shows how to retrieve an attachment that was created in a 1.x database with a 2.x API.

    Dictionary attachments = document.getDictionary("_attachments");
    Blob blob = attachments != null ? attachments.getBlob("avatar") : null;
    byte[] content = blob != null ? blob.getContent() : null;

    Replication Compatibility

    The current replication protocol is not backwards compatible with the 1.x replication protocol. Therefore, to use replication with Couchbase Lite 2.x, the target Sync Gateway instance must also be upgraded to 2.x.

    Sync Gateway 2.x will continue to accept clients that connect through the 1.x protocol. It will automatically use the 1.x replication protocol when a Couchbase Lite 1.x client connects through http://localhost:4984/db and the 2.0 replication protocol when a Couchbase Lite 2.0 client connects through ws://localhost:4984/db. This allows for a smoother transition to get all your user base onto a version of your application built with Couchbase Lite 2.x.