General Upgrade Notes

The upgrade information given below is generally true for all versions of Oracle NoSQL Database.
  • Installing new software requires that each Storage Node be restarted.
  • You do not need to invoke makebootconfig command while upgrading your data store.
  • When your data store has more than one Storage Node, you can use the following command to understand the order of upgrade. For example,
    show upgrade-order   
s2
s3
  • When upgrading the software while the Storage Node is stopped, it is recommended to move the existing log files under $KVROOT and $KVROOT/<storename>/log to another directory.
  • When upgrading your data store, place the new software version in a new $KVHOME directory on a Storage Node running the admin service. Here the new $KVHOME directory is referred to as $NEW_KVHOME. If the $KVHOME and $NEW_KVHOME directories are shared by multiple Storage Nodes (for example, using NFS), maintain both directories while the upgrade is in progress. After the upgrade is complete, you no longer need the original $KVHOME directory. Before removing the original $KVHOME directory you must modify the start up scripts on each Storage Node ( e.g. ~/.bashrc where you have defined $KVHOME) to modify the value of existing $KVHOME and replace it with the value of $NEW_KVHOME so that the Storage Node uses the new software.

Enabling new features

The data store maintains a store-wide, system-level compatibility state, which controls when new, potentially incompatible features can be enabled after upgrade across the KV ecosystem. System compatibility state defines minimal versions with which system components remain compatible. A validation mechanism checks the system compatible state and prevents incompatible data from being written until the state advances to a version that is compatible with the new feature. It also defines a clear cutover point, so applications see consistent, well-defined behavior for persisted data.

Release 26.1 introduces the row creation time and user-supplied metadata features. Because these features add new metadata to row and write operations respectively, the data store's system compatibility state must be updated before they can be used.

After upgrading to 26.1, any rows that you add before you enable the data store’s compatibility state will have an ill-defined creation time. To ensure the values of creation times are accurate, you must only obtain creation times from rows that are inserted after the System Compatibility Version (SCV) is enabled to 26.1.

Additionally, for user-supplied metadata, rows written before enablement do not include the metadata. As a result, older direct driver/SDKs could potentially require application-level handling if they encounter rows that include user-supplied metadata until the direct driver/SDKs are upgraded.

To avoid these incompatibilities, update the system compatibility version by running the plan upgrade-scv command after upgrading the data store and its associated components. For details, see Post-Upgrade Procedure.

Compatibility with Release 25.3 experimental row metadata feature

From Release 26.1, the preview-only row-metadata feature introduced in Release 25.3 is replaced by the user-supplied metadata, which has slightly different semantics. When Oracle NoSQL Database reads older records that contain row metadata written with the 25.3 API, it interprets them as user-supplied metadata. You must use the user-supplied metadata APIs for querying and writing.

To use the user-supplied metadata feature, you must complete the Post-Upgrade Procedure.

Upgrade requirement for multi-region deployments

In multi-region deployments, all regions must be upgraded to 26.1 before enabling the user-supplied metadata feature through the SCV upgrade procedure. For more details, see Post-Upgrade Procedure.