Sidegrade

oak-upgrade module creates an executable jar file. It can be invoked like this:

java -jar oak-upgrade-*.jar [options] source destination

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.

Following parameters should be used for the JDBC node store:

• Source database: --src-password=... --src-user=...
• Desination database: --user=... --password=...

Examples:

java -jar oak-upgrade-*.jar \
    path/to/the/repository \
    mongodb://localhost:27017/oak

java -jar oak-upgrade-*.jar \
    --user=sa --password=sa \
    mongodb://localhost:27017/oak \
    jdbc:h2:path/to/repo

Upgrade

In order to upgrade Jackrabbit 2 repository to the new node store, pass the path to the repository directory as the source parameter. Optionally, you may also pass the path to the repository.xml file as a separate parameter. Examples:

java -jar oak-upgrade-*.jar \
    path/to/the/jr2/repository \
    path/to/repository.xml \
    path/to/the/new/repository

java -jar oak-upgrade-*.jar \
    path/to/the/jr2/repository \
    mongodb://localhost:27017/oak

Migrating blob store

By default, the oak-upgrade only copies the binary references, so you need to reuse the same blob/data store in the new repository. However, it's also possible to migrate binaries as well using the --copy-binaries parameter. Following migration paths are possible for the binaries. The internal means that the binaries are stored inside the segment or document node store:

¹ The S3DataStore will take care of this migration automatically, no need to use oak-upgrade
² The storage might be simple cloned without using oak2oak

Following parameters can be used to define the source and the destination blob stores:

Use the --copy-binaries parameter to instruct the oak-upgrade to copy binaries.

Example:

java -jar oak-upgrade-*.jar \
    --copy-binaries \
    --src-datastore=/old/repository/datastore \
    --fileblobstore=/new/repository/datastore \
    /old/repository \
    /new/repository

accessKey=...
secretKey=...
s3Bucket=...
s3Region=eu-west-1
s3EndPoint=s3-eu-west-1.amazonaws.com

connectionTimeout=120000
socketTimeout=120000
maxConnections=40
writeThreads=30
maxErrorRetry=10

Migrating a subtree

It's possible to define a list of content subtrees to include or exclude during the migration. By default, the whole repository gets copied. In order to copy only a subtree, use the --include-paths. For example, the following command will copy only the /content/site and /content/other_site subtrees:

java -jar oak-upgrade-*.jar \
    --include-paths=/content/site,/content/other_site \
    /old/repository \
    /new/repository

You may also exclude specific paths from being copied. Following command will copy the whole content without the /content/redundant_site:

java -jar oak-upgrade-*.jar \
    --exclude-paths=/content/redundant_site \
    /old/repository \
    /new/repository

By default, the source repository replaces the destination repository (if there's one). For instance, in the first example if the /content/site node already exists in the destination repository, it'll be removed and replaced by the source node. It's also possible to merge content from the source repository with --merge-paths:

java -jar oak-upgrade-*.jar \
    --include-paths=/content/site \
    --merge-paths=/content/site \
    /old/repository \
    /new/repository

Please notice that in the last example it's necessary to narrow the migration scope using --include-paths parameter.

A merge might fail with an OakConstraint0030 message if an already existing node has been renamed at the source or destination repository. This can be observed for nodes with an UUID property. The merging node would be copied into the destination repository which already contains the node under a different name with the same UUID.

Version history copying

By default, the whole version storage is migrated. This includes referenced version histories (their versionable node still exists in the repository) and orphaned ones (their versionable node no longer exists). oak-upgrade allows to skip the orphaned version histories to make the migration faster and the destination repository smaller. It's also possible to define a maximum age for the version histories (both referenced and orphaned) to be copied.

There are two parameters: --copy-orphaned-versions and --copy-versions. Both accepts boolean values or a YYYY-MM-DD date. Examples:

# only copy referenced versions
java -jar oak-upgrade-*.jar \
    --copy-orphaned-versions=false \
    /old/repository /new/repository

# don't copy any versions at all
java -jar oak-upgrade-*.jar \
    --copy-versions=false \
    /old/repository /new/repository

# copy referenced versions created after 2010
# and orphaned version created after 2011
java -jar oak-upgrade-*.jar \
    --copy-versions=2010-01-01 \
    --copy-orphaned-versions=2011-01-01 \
    /old/repository /new/repository

Incremental migration

If an existing repository is passed as the destination, then only a diff between source and destination will be migrated. It allows to migrate the content in a few iterations. For instance, following case is possible:

1. migrate a large repository a week before go-live
2. run the migration again every night (only the recent changes are copied)
3. run the migration one final time before go-live

Interrupting the migration

The migration might be stop at any time using ^C. Resume the migration running the same command which was used to start it.

Custom initializers and commit hooks

It's possible to inject custom logic into the upgrade process, by implementing RepositoryInitializer or CommitHook.

In order to do that, create a new Maven project, with appropriate implementation. Then create following file:

src/main/resources/META-INF/services/org.apache.jackrabbit.oak.spi.commit.CommitHook

The file should contain just one line - the name of the class with the CoomitHook implementation. Build the project and attach the JAR to the oak-upgrade class path:

java -cp my-commit-hook.jar:oak-upgrade-*.jar org.apache.jackrabbit.oak.upgrade.cli.OakUpgrade [normal oak-upgrade parameters]

A custom RepositoryInitializer can be injected in a similar way.

Other parameters

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 and breaks:

Checkpoints won't be copied, because no external datastore has been specified. This will result in the full repository reindexing on the first start. Use --skip-checkpoints to force the migration or see https://jackrabbit.apache.org/oak/docs/migration.html#Checkpoints_migration for more info.

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 reindexed on the first startup. It may be a long process, especially for the big instance. Repository won't be usable until the reindexing process is done. Use --skip-checkpoints option to suppress the warning.