This section describes how to update your Oracle NoSQL Database deployment from Release 1 to Release 2.
Installing new software requires that each node be restarted. Depending on the configuration of your store, it may be possible to upgrade it to release 2 while the store continues to remain online and available to clients. Online upgrade can succeed if the store's replication factor greater than 2, and if the store's Topology contains only a single Datacenter.
With a store that has a replication factor greater than two, the shards can maintain their majorities and continue reading and writing data on behalf of clients while their components are restarted, one at a time. If the replication factor is 2 or 1, then the majorities cannot be maintained across the restart of a single node, and each shard will become unavailable for a short time.
Online upgrade is not supported for a store with a Release 1 Topology that contains multiple Datacenters. If your store has such a topology, please contact technical support before starting to upgrade it.
Release 2 changes the internal protocols by which the components of a store communicate with one other. Limited cross-version compatibility has been implemented. Components (including applications that use the embedded client library) running release 1 and components running release 2 can communicate with one another, so that a store can remain running and available to clients during the upgrade. However, operations that change the configuration of the store should not be attempted while the upgrade is in progress.
Similarly, release 2 changes the persistent meta-data that is kept by the components of the store. When a component, such as the Admin or the Replication Node, first starts on the new software, it will automatically convert its meta-data to the new format. Therefore it is not possible to downgrade to the older release without restoring the store from a previous backup.
Before beginning the upgrade process, you should take a backup of the store by creating a snapshot. See Taking a Snapshot.
In Oracle NoSQL Database, configuration changes and other
administrative activities involve
plans. In release 2, the execution
or restarting of plans that were created in Release 1 is
not supported. Any plans that are not in a completed
state should be canceled before the upgrade begins. For
information about plans, see Plans.
During the upgrade process, you should not create any plans until all services in the store have been upgraded.
Application programs that use the kvstore client library should be upgraded to the new software version as soon as possible after the service components have been upgraded. New clients can also be used with an old store, so it is possible to test Release 2 clients before upgrading the store services.
When Oracle NoSQL Database is first installed, it is placed in a KVHOME
directory, which may be per-machine, or optionally be
shared by multiple Storage Nodes (that is, via
NFS). Here, we call this existing KVHOME location,
OLD_KVHOME.
It is useful for installations to adopt a convention
for KVHOME that includes the release number. That
is, always use a KVHOME location such as
/var/kv/kv-M.N.O, where
M.N.O are the release.major.minor
numbers. This can be easily achieved by simply
unzip/untarring the distribution into a common
directory (/var/kv in this example).
Installing new software requires that each node be restarted. Oracle NoSQL Database is a replicated system, so to avoid excessive failover events it is recommended that any node that is running as a MASTER be restarted after all those marked REPLICA. This command tells you which nodes are MASTER and REPLICA:
java -jar KVHOME/lib/kvstore.jar ping -host <hostname> -port <port>
Use the host and registry port for any active node in the store.
To upgrade to new software, for each node (machine) in the system do the following steps. These steps should be done serially to minimize possible performance impact:
Place the updated software in a new KVHOME directory — referred to here as NEW_KVHOME. If nodes share this directory using NFS, this only needs to be done once for each shared directory
If you have configured the node to automatically
start the Storage Node Agent on reboot using
/etc/init.d, Upstart, or some other mechanism
(for example, using
nohup java -jar KVHOME/lib/kvstore.jar start -root <kvroot> ...& ),
first modify that script to point to NEW_KVHOME.
For each KVROOT (usually, once per node):
Stop the Storage Node using the old code:
java -jar OLD_KVHOME/lib/kvstore.jar stop -root <kvroot> \ [-config <configfile>]
Restart the Storage Node using the new code:
nohup java -jar NEW_KVHOME/lib/kvstore.jar start -root <kvroot> \
[-config <configfile>] &
If the system is configured to automatically restart the Storage Node Agent, this step may not be necessary.
Make sure that any administrative scripts or other files that reference OLD_KVHOME have been changed.
Once you are done, OLD_KVHOME can be removed.
The Release 1 administrative CLI program is not compatible with a Release 2 Admin service, nor vice-versa. Make sure that you are using the compatible library when running the CLI.
It may be necessary to clear the cache of your web browser when you first connect to the Release 2 Admin Console.