Steps to Upgrade - Examples

Upgrading a data store from an existing release to a new release can be accomplished one Storage Node at a time.

The data store upgrade involves the following activities:

1. Install the new software and sequentially restart all the Storage Nodes.

2. Upgrade all the components of the data store, including the proxy, direct drivers, SDKs, and Xregion service agents.

3. Run the plan upgrade-scv command to enable new features as described in the Post-Upgrade Procedure topic.
4. Deploy new application code to start using the new features.

Note: Run the plan upgrade-scv command only after all data store components have been upgraded. Enabling new features before completing the component upgrades may cause non-upgraded components to operate incorrectly or become incompatible with the upgraded data store.

Different upgrade scenarios are captured in the examples below. Each example shows how to upgrade your Oracle NoSQL Database software to a new release.

Example 1: Upgrading a data store with a single Storage Node.

In this example you are upgrading your Oracle NoSQL Database from version 25.3.21 to version 26.1.x.

Prerequisites:

• The data store is installed with version 25.3.21 and has a capacity 1, replication factor 1.

• $KVHOME is /var/kv/kv-25.3.21

• $KVROOT is /var/kv/kv-25.3.21/kvroot

• $KVHOST is the hostname of your Storage Node.

Procedure:

• Invoke the runadmin command to start the Admin command line interface (CLI) utility on the Storage Node. This command starts the kv prompt.

  java -jar $KVHOME/lib/kvstore.jar runadmin -host $KVHOST
  -port 5000 -security $KVROOT/security/root.login

  Use the ping command to list the admin service and all managed services of your Storage Node.

  kv→ping

  Output:

  Pinging components of store mystore based upon topology sequence #154
  
  150 partitions and 1 storage nodes
  Time: 2026-01-30 11:47:26 UTC   Version: 25.3.21
  Shard Status: healthy: 1 writable-degraded: 0 read-only: 0 offline: 0 total: 1
  Admin Status: healthy
  Zone [name=zone1 id=zn1 type=PRIMARY allowArbiters=false masterAffinity=false]   RN Status: online: 1 read-only: 0 offline: 0
  Storage Node [sn1] on <XX>.com: 5000    Zone: [name=zone1 id=zn1 type=PRIMARY allowArbiters=false masterAffinity=false]    Status: RUNNING   Ver: 25.3.21 2025-10-08 13:27:27 UTC  Build id: c208f3d60d11 Edition: Enterprise    isMasterBalanced: true    serviceStartTime: 2026-01-21 08:41:13 UTC
      Admin [admin1]        Status: RUNNING,MASTER    serviceStartTime: 2026-01-21 08:42:13 UTC    stateChangeTime: 2026-01-21 08:42:13 UTC    availableStorageSize: 2 GB
      Rep Node [rg1-rn1]    Status: RUNNING,MASTER sequenceNumber: 82,217 haPort: 5006 availableStorageSize: 337 GB storageType: HD    serviceStartTime: 2026-01-21 08:43:21 UTC    stateChangeTime: 2026-01-21 08:43:23 UTC

• Verify that the Storage node are at or above the prerequisite software version needed to upgrade to the current version.

  kv-> verify prerequisite

  Output:

  Verify: starting verification of store mystore based upon topology sequence #154
  
  150 partitions and 1 storage nodes
  Time: 2026-01-30 11:48:08 UTC   Version: 25.3.21
  See phoenix126166:kvhome/kvroot/mystore/log/mystore_{0..N}.log for progress messages
  Verify prerequisite: Storage Node [sn1] on <XX>.com: 5000    Zone: [name=zone1 id=zn1 type=PRIMARY allowArbiters=false masterAffinity=false]    Status: RUNNING   Ver: 25.3.21 2025-10-08 13:27:27 UTC  Build id: c208f3d60d11 Edition: Enterprise    isMasterBalanced: true    serviceStartTime: 2026-01-21 08:41:13 UTC
  
  Verification complete, no violations.

• To upgrade your data store, you need to install the latest software in your Storage Node. See Install and verify your NoSQL Database installation for more details.

• Stop the Oracle NoSQL Database Storage Node Agent and services related to the root directory of the current Oracle NoSQL Database (25.3.21).

  java -Xmx64m -Xms64m -jar $KVHOME/lib/kvstore.jar stop
  
  -root $KVROOT

• Restart the Storage Node using the updated software release (kv-26.1.x). Here $NEW_KVHOME is /var/kv/kv-26.1.x and $KVROOT is /var/kv/kv-25.3.21/kvroot

  nohup java -Xmx64m -Xms64m -jar $NEW_KVHOME/lib/kvstore.jar
  start -root $KVROOT &

• Invoke the runadmin command to start the Admin command line interface (CLI) utility on the Storage Node which is now running the updated software release. This command starts the kv prompt.

  java -Xmx64m -Xms64m -jar $NEW_KVHOME/lib/kvstore.jar
  runadmin -port 5000 -host $KVHOST
  
  -security $KVROOT/security/root.login

• Run the post-upgrade procedure to enable new features. For details, see Post-Upgrade Procedure.

Example 2: Error while directly upgrading Oracle NoSQL Database from a very old version to the current version.

Case 1: In this example you want to upgrade Oracle NoSQL Database from version 22.1.22 to version 26.1.x.

Prerequisites:

• The data store is installed with version 22.1.22 and has a capacity 1, replication factor 1.

• $KVHOME is /var/kv/kv-22.1.22

• $KVROOT is /var/kv/kv-22.1.22/kvroot

Procedure:

The following example shows the error you encounter when you try to upgrade from version 22.1.22 to version 26.1.x.

• To upgrade your data store, you need to install the latest software in your Storage Node. See Install and verify your NoSQL Database installation for more details.

• Stop the Oracle NoSQL Database Storage Node Agent and services related to the root directory of the current Oracle NoSQL Database (22.1.22).

  java -Xmx64m -Xms64m -jar $KVHOME/lib/kvstore.jar stop -root $KVROOT

• Restart the Storage Node using the updated software release (26.1.x).

  nohup java -Xmx64m -Xms64m -jar $NEW_KVHOME/lib/kvstore.jar start -root $KVROOT &

  You get an output as shown below, which implies an error has occurred.

  [1]+ Exit 1 nohup java -Xmx64m -Xms64m -jar /var/kv/kv-26.1.x/lib/kvstore.jar start -root /var/kv/kv-22.1.22/kvroot

  Open the nohup.out file to view the error.

  vi nohup.out Failed to start SNA: The previous software version 22.1.22 does not satisfy the
  prerequisite for 26.1.x which requires version 24.1.12 or later.

  To avoid this error, you must upgrade the data store from 22.1.22 to any 24.1.* release first and then upgrade it to 26.1.x.

Case 2: In this example you want to upgrade Oracle NoSQL Database from version 19.5.9 to version 24.1.11.

Prerequisites:

• The data store is installed with version 19.5.9 and has a capacity 1, replication factor 1.

• $KVHOME is /var/kv/kv-19.5.9

• $KVROOT is /var/kv/kv-19.5.9/kvroot

Procedure:

The following example shows the error you encounter when you try to upgrade from version 19.5.9 to version 24.1.11.

• To upgrade your data store, you need to install the latest software in your Storage Node. See Install and verify your NoSQL Database installation for more details.

• Stop the Oracle NoSQL Database Storage Node Agent and services related to the root directory of the current Oracle NoSQL Database (19.5.9).

  java -Xmx64m -Xms64m -jar $KVHOME/lib/kvstore.jar stop
  
  -root $KVROOT

• Restart the Storage Node using the updated software release (24.1.11).

  nohup java -Xmx64m -Xms64m -jar $NEW_KVHOME/lib/kvstore.jar start
  
  -root $KVROOT &

  You get an output as shown below, which implies an error has occurred.

  [1]+  Exit 1 nohup java -Xmx64m -Xms64m -jar
  /var/kv/kv-24.1.11/lib/kvstore.jar start
  
  -root /var/kv/kv-19.5.9/kvroot

  Open the nohup.out file to view the error.

  vi nohup.out
  Failed to start SNA: The previous software version 19.5.9 does not satisfy
  the prerequisite for 24.1.11 which requires version 20.1.12 or later.

  To avoid this error, you need to upgrade the data store from 19.5.9 to any 20.x release and then upgrade it to 24.1.11.

Example 3: Upgrading a data store with more than one Storage Node.

Prerequisites:

• The data store is installed with version 24.1.15 and has a capacity 1, replication factor 1. You have two Storage Nodes in your data store.

• $KVHOME is /var/kv/kv-24.1.15

• $KVROOT is /var/kv/kv-24.1.15/kvroot

• $KVHOST is the hostname of your first Storage Node.

Procedure:

• Invoke the runadmin command to start the Admin command line interface (CLI) utility on the Storage Node which is now running the existing software release (24.1.15). This command starts the kv prompt.

  java -jar $KVHOME/lib/kvstore.jar runadmin -host $KVHOST -port 5000 -security $KVROOT/security/root.login

• Use ping command to return information about the runtime entities of your data store.

  kv→ ping

  Output:

  Pinging components of store mystore based upon topology sequence #107
  100 partitions and 2 storage nodes
  Time: 2026-02-16 11:09:31 UTC   Version: 24.1.15
  Shard Status: healthy: 2 writable-degraded: 0 read-only: 0 offline: 0 total: 2
  Admin Status: healthy
  Zone [name=zone1 id=zn1 type=PRIMARY allowArbiters=false masterAffinity=false]   RN Status: online: 2 read-only: 0 offline: 0
  Storage Node [sn1] on <XX>.com: 5000    Zone: [name=zone1 id=zn1 type=PRIMARY allowArbiters=false masterAffinity=false]    Status: RUNNING   Ver: 24.1.15 2024-04-11 20:02:19 UTC  Build id: e0c93c1f1395 Edition: Enterprise    isMasterBalanced: true    serviceStartTime: 2026-02-16 10:39:27 UTC
    Admin [admin1]        Status: RUNNING,MASTER    serviceStartTime: 2026-02-16 10:40:23 UTC    stateChangeTime: 2026-02-16 10:40:23 UTC    availableStorageSize: 2 GB
    Rep Node [rg1-rn1]    Status: RUNNING,MASTER sequenceNumber: 140 haPort: 5011 availableStorageSize: 341 GB storageType: HD    serviceStartTime: 2026-02-16 10:41:40 UTC    stateChangeTime: 2026-02-16 10:41:42 UTC
  Storage Node [sn2] on <XX>.com: 8000    Zone: [name=zone1 id=zn1 type=PRIMARY allowArbiters=false masterAffinity=false]    Status: RUNNING   Ver: 24.1.15 2024-04-11 20:02:19 UTC  Build id: e0c93c1f1395 Edition: Enterprise    isMasterBalanced: true    serviceStartTime: 2026-02-16 10:39:37 UTC
    Admin [admin2]        Status: RUNNING,REPLICA    serviceStartTime: 2026-02-16 10:41:16 UTC    stateChangeTime: 2026-02-16 10:41:16 UTC    availableStorageSize: 2 GB
    Rep Node [rg2-rn1]    Status: RUNNING,MASTER sequenceNumber: 139 haPort: 8011 availableStorageSize: 341 GB storageType: HD    serviceStartTime: 2026-02-16 10:41:52 UTC    stateChangeTime: 2026-02-16 10:41:54 UTC

• Verify that the Storage Nodes are at or above the prerequisite software version needed to upgrade to the current version.

  kv-> verify prerequisite

  Output:

  Verify: starting verification of store mystore based upon topology sequence #107
  100 partitions and 2 storage nodes
  Time: 2026-02-16 11:11:58 UTC   Version: 24.1.15
  See localhost:kvroot/mystore/log/mystore_{0..N}.log for progress messages
  Verify prerequisite: Storage Node [sn1] on <XX>.com: 5000    Zone: [name=zone1 id=zn1 type=PRIMARY allowArbiters=false masterAffinity=false]    Status: RUNNING   Ver: 24.1.15 2024-04-11 20:02:19 UTC  Build id: e0c93c1f1395 Edition: Enterprise    isMasterBalanced: true    serviceStartTime: 2026-02-16 10:39:27 UTC
  Verify prerequisite: Storage Node [sn2] on <XX>.com: 8000    Zone: [name=zone1 id=zn1 type=PRIMARY allowArbiters=false masterAffinity=false]    Status: RUNNING   Ver: 24.1.15 2024-04-11 20:02:19 UTC  Build id: e0c93c1f1395 Edition: Enterprise    isMasterBalanced: true    serviceStartTime: 2026-02-16 10:39:37 UTC
  
  Verification complete, no violations.

• To upgrade your data store, you need to install the latest software in all your Storage Nodes. In your first Storage Nodes (sn1), install the new version of the software. See Install and verify your NoSQL Database installation for more details.

• Stop the Oracle NoSQL Database Storage Node Agent and services related to the root directory of the current Oracle NoSQL Database (24.1.15).

  java -Xmx64m -Xms64m -jar $KVHOME/lib/kvstore.jar stop -root $KVROOT

• Restart the first Storage Node using the updated software release (26.1.x). Here $NEW_KVHOME is /var/kv/kv-26.1.x and $KVROOT is /var/kv/kv-24.1.15/kvroot.

  nohup java -Xmx64m -Xms64m -jar $NEW_KVHOME/lib/kvstore.jar start -root $KVROOT &

• Invoke the runadmin command to start the Admin command line interface (CLI) utility on the Storage Node which is now running the updated software release. If prompted, enter your log in credentials.

  This command starts the kv prompt.

  java -Xmx64m -Xms64m -jar $NEW_KVHOME/lib/kvstore.jar
  runadmin -port 5000 -host $KVHOST -security
  $KVROOT/security/root.login

  Login as:root
  root's password:
  Logged in to Admin as root
  Connected to Admin at: <XX>.com:5000

• Verify the store configuration to check if the upgrade for the first Storage Node (sn1) is completed successfully.

  kv-> verify upgrade

  Output:

  Verify: starting verification of store mystore based upon topology sequence #107
  100 partitions and 2 storage nodes
  Time: 2026-02-16 12:19:44 UTC   Version: 24.1.15
  See localhost:kvroot1/mystore/log/mystore_{0..N}.log for progress messages
  Verify upgrade: Storage Node [sn1] on <XX>.com:5000    Zone: [name=zone1 id=zn1 type=PRIMARY allowArbiters=false masterAffinity=false]    Status: RUNNING   Ver: 26.1.x 2026-01-20 19:42:19 UTC  Build id: 537e0a600f2b Edition: Enterprise    isMasterBalanced: true    serviceStartTime: 2026-02-16 12:17:40 UTC
  Verify:         sn2: Node needs to be upgraded from 24.1.15 to version 26.1.x or newer
  Verify upgrade: Storage Node [sn2] on <XX>.com:8000    Zone: [name=zone1 id=zn1 type=PRIMARY allowArbiters=false masterAffinity=false]    Status: RUNNING   Ver: 24.1.15 2024-04-11 20:02:19 UTC  Build id: e0c93c1f1395 Edition: Enterprise    isMasterBalanced: true    serviceStartTime: 2026-02-16 11:56:56 UTC
  
  Verification complete, 0 violations, 1 note found.
  Verification note: [sn2]    Node needs to be upgraded from 24.1.15 to version 26.1.x or newer

• Obtain an ordered list of the Storage Nodes to upgrade. The output below shows that the Storage Node sn2 needs to be upgraded.

  kv-> show upgrade-order

  Output:

  Calculating upgrade order,target version: 26.1.x,prerequisite: 24.1.12 sn2

• In your second Storage Node ( sn2), install the new version of the software. See Install and verify your NoSQL Database installation for more details.

  Note: The software (kv-26.1.x.zip) has already been copied from Storage Node sn1 to the Storage Node sn2.

• Stop the Oracle NoSQL Database Storage Node Agent and services related to the root directory of the current Oracle NoSQL Database ( 24.1.15).

  java -Xmx64m -Xms64m -jar $KVHOME/lib/kvstore.jar stop -root $KVROOT

• Restart the second Storage Node using the updated software release (26.1.x). Here $NEW_KVHOME is /var/kv/kv-26.1.x and $KVROOT is /var/kv/kv-24.1.15/kvroot.

  nohup java -Xmx64m -Xms64m -jar $NEW_KVHOME/lib/kvstore.jar start -root $KVROOT &

• Invoke the runadmin command to start the Admin command line interface (CLI) utility on the Storage Node which is now running the updated software release. If prompted, enter your log in credentials.

  Here $KVHOST is the host name of the first Storage Node (sn1).

  java -Xmx64m -Xms64m -jar $NEW_KVHOME/lib/kvstore.jar
  runadmin -port 5000 -host $KVHOST -security
  $KVROOT/security/root.login

  Login as:root
  root's password:
  Logged in to Admin as root
  Connected to Admin at: <XX>.com:8000

• Verify the store configuration to check if the upgrade for the second Storage Node (sn2) is completed successfully.

  kv-> verify upgrade

  Output:

  Verify: starting verification of store mystore based upon topology sequence #107
  100 partitions and 2 storage nodes
  Time: 2026-02-16 12:34:36 UTC   Version: 26.1.x
  See localhost:kvroot1/mystore/log/mystore_{0..N}.log for progress messages
  Verify upgrade: Storage Node [sn1] on <XX>.com:5000    Zone: [name=zone1 id=zn1 type=PRIMARY allowArbiters=false masterAffinity=false]    Status: RUNNING   Ver: 26.1.x 2026-01-20 19:42:19 UTC  Build id: 537e0a600f2b Edition: Enterprise    isMasterBalanced: true    serviceStartTime: 2026-02-16 12:17:40 UTC
  Verify upgrade: Storage Node [sn2] on <XX>.com:8000    Zone: [name=zone1 id=zn1 type=PRIMARY allowArbiters=false masterAffinity=false]    Status: RUNNING   Ver: 26.1.x 2026-01-20 19:42:19 UTC  Build id: 537e0a600f2b Edition: Enterprise    isMasterBalanced: true    serviceStartTime: 2026-02-16 12:30:26 UTC
  
  Verification complete, 0 violations, 2 notes found.
  Verification note: [rg1-rn1]    The system compatibility state of rg1-rn1 is not upgraded to or consistent for 26.1: current state is STORE_UPGRADED. Some features may not be supported. Execute the command `plan upgrade-scv -version 26.1` from the admin CLI to upgrade.
  Verification note: [rg2-rn1]    The system compatibility state of rg2-rn1 is not upgraded to or consistent for 26.1: current state is STORE_UPGRADED. Some features may not be supported. Execute the command `plan upgrade-scv -version 26.1` from the admin CLI to upgrade.

  Note: The output displays verification notes with the system compatibility status and a suggestion to run the plan upgrade-scv command. You must run the plan as the final step of this upgrade procedure, that is, after all the Storage nodes and any associated components are upgraded.

• Check if any other Storage Node need to be upgraded.

  kv-> show upgrade-order

  Calculating upgrade order, target version: 26.1.x, prerequisite: 24.1.12
  There are no nodes that need to be upgraded

  The output shows the upgrade for all Storage Nodes is complete.

• Run the post-upgrade procedure to enable new features. For details, see Post-Upgrade Procedure.