svn commit: r1786673 - in /jackrabbit/oak/trunk: oak-doc/src/site/markdown/migration.md oak-upgrade/src/main/java/org/apache/jackrabbit/oak/upgrade/RepositorySidegrade.java

[to...@apache.org]

Author: tomekr
Date: Mon Mar 13 12:47:05 2017
New Revision: 1786673

URL: http://svn.apache.org/viewvc?rev=1786673&view=rev
Log:
OAK-5920 Checkpoint migration will fail if the MissingBlobStore is used

-improved the warning message and update the documentation

Modified:
    jackrabbit/oak/trunk/oak-doc/src/site/markdown/migration.md
    jackrabbit/oak/trunk/oak-upgrade/src/main/java/org/apache/jackrabbit/oak/upgrade/RepositorySidegrade.java

Modified: jackrabbit/oak/trunk/oak-doc/src/site/markdown/migration.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/migration.md?rev=1786673&r1=1786672&r2=1786673&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/migration.md (original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/migration.md Mon Mar 13 12:47:05 2017
@@ -38,6 +38,7 @@ The `oak-upgrade` module allows to do an
 The `source` and `destination` are the node store paths/URIs. Following node stores are supported:
 
 * `SegmentNodeStore` - use a path to the `repository` directory,
+* old `SegmentNodeStore` (Oak < 1.6) - use the `segment-old:` prefix and the path to the `repository` directory,
 * `DocumentNodeStore` with MongoDB - `mongodb://host:port/database`,
 * `DocumentNodeStore` with a RDB - `jdbc:...`. It requires passing user and password with separate parameters.
 
@@ -207,6 +208,19 @@ A custom `RepositoryInitializer` can be
 
 The full list of supported parameters can be displayed using `--help` switch.
 
+### Checkpoints migration
+
+When migrating an old SegmentMK repository (pre-Oak 1.6) to the new SegmentMK (Oak >= 1.6), the checkpoints are migrated as well. This allows to avoid reindexing when the Oak is being run for the first time on the new repository. However, the checkpoints won't be migrated in following cases:
+
+* custom include-, exclude- or merge- paths are specified or
+* the binaries are copied by references, no source datastore is specified and two different checkpoints contains different binary under the same path.
+
+In the second case oak-upgrade emits following warning:
+
+    Checkpoints won't be copied, because no external datastore has been specified. This will result in the full repository reindexing on the first start.
+
+The easiest way to fix this issue is specifying the source datastore in the command line options (eg. `--src-datastore` or `--src-s3datastore`). The warning may also be ignored, but in this case the repository will be fully reindexing on the first startup, which may be a long process, especially for large instances. Repository won't be usable until the reindexing process is done.
+
 ## Online blob migration with SplitBlobStore
 
 Oak offers one more way to migrate blob store, without turning off the instance (a few restarts might be required, but the migration process is done during normal repository operation).

Modified: jackrabbit/oak/trunk/oak-upgrade/src/main/java/org/apache/jackrabbit/oak/upgrade/RepositorySidegrade.java
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-upgrade/src/main/java/org/apache/jackrabbit/oak/upgrade/RepositorySidegrade.java?rev=1786673&r1=1786672&r2=1786673&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-upgrade/src/main/java/org/apache/jackrabbit/oak/upgrade/RepositorySidegrade.java (original)
+++ jackrabbit/oak/trunk/oak-upgrade/src/main/java/org/apache/jackrabbit/oak/upgrade/RepositorySidegrade.java Mon Mar 13 12:47:05 2017
@@ -311,7 +311,7 @@ public class RepositorySidegrade {
             } catch(UnsupportedOperationException e) {
                 removeCheckpoints();
                 checkpointsCopied = false;
-                LOG.warn("Can't copy checkpoints without the access to the external blob store; migration will proceed");
+                LOG.warn("Checkpoints won't be copied, because no external datastore has been specified. This will result in the full repository reindexing on the first start. See https://jackrabbit.apache.org/oak/docs/migration.html#Checkpoints_migration for more info.");
             }
             if (!checkpointsCopied) {
                 LOG.info("Copying checkpoints is not supported for this combination of node stores");