Previous Next JavaScript must be enabled to correctly display this content

## 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. Different scenarios of upgrade are captured in the examples below. Each example shows how to upgrade your Oracle NoSQL Database software to a new release.

Example1: In this example you are upgrading your Oracle NoSQL Database from version 22.1.7 to version 24.1.11. The data store has a capacity 1 and replication factor 1. Here `$KVHOME` is `/var/kv/kv-22.1.7`, `$KVROOT` is `/var/kv/kv-22.1.7/kvroot` and `$KVHOST` is the hostname of your Storage Node.

- 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 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: 2024-04-05 06:13:33 UTC   Version: 22.1.7
      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 localhost:5000
      Zone: [name=zone1 id=zn1 type=PRIMARY allowArbiters=false masterAffinity=false]
      Status: RUNNING   Ver:  2024-04-05 06:14:33 UTC
      Build id: 1473c1dac49c Edition: Enterprise
              Admin [admin1]          Status: RUNNING,MASTER
              Rep Node [rg1-rn1]      Status: RUNNING,MASTER
              sequenceNumber:330 haPort:5006 available storage size:1023 MB

- 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: 2024-04-05 09:27:43 UTC   Version: 22.1.7
      See localhost:/var/kv/kv-22.1.7/kvroot/mystore/log/mystore_{0..N}.log
      for progress messages

      Verify prerequisite: Storage Node [sn1] on localhost: 5000
      Zone: [name=zone1 id=zn1 type=PRIMARY allowArbiters=false masterAffinity=false]
      Status: RUNNING   Ver: 22.1.7 2024-04-05 16:36:54 UTC  Build id: 61b68fb1a3ec
      Edition: Enterprise    isMasterBalanced: true
      serviceStartTime: 2024-04-05 08:55:49 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 (`22.1.7`).

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

- Restart the Storage Node using the updated software release(`24.1.11`). Here `$NEW_KVHOME` is `/var/kv/kv-24.1.11` and `$KVROOT` is `/var/kv/kv-22.1.7/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

- Verify the store configuration to check if the upgrade is completed successfully.

      kv-> verify configuration

  Output:

      Verify: starting verification of store mystore based upon topology sequence #154
      150 partitions and 1 storage nodes
      Time: 2024-04-05 09:33:10 UTC   Version: 24.1.11
      See localhost:/var/kv/kv-22.1.7/kvroot/mystore/log/mystore_{0..N}.log for progress messages
      Verify: Shard Status: healthy: 1 writable-degraded: 0 read-only: 0 offline: 0 total: 1
      Verify: Admin Status: healthy
      Verify: Zone [name=zone1 id=zn1 type=PRIMARY allowArbiters=false masterAffinity=false]
      RN Status: online: 1 read-only: 0 offline: 0
      Verify: == checking storage node sn1 ==
      Verify: Storage Node [sn1] on localhost: 5000
      Zone: [name=zone1 id=zn1 type=PRIMARY allowArbiters=false masterAffinity=false]
      Status: RUNNING   Ver: 24.1.11 2024-04-05 21:25:44 UTC  Build id: 477e7f102ab4
      Edition: Enterprise    isMasterBalanced: true
      serviceStartTime: 2024-04-05 09:32:29 UTC
      Verify:         Admin [admin1]
      Status: RUNNING,MASTER  serviceStartTime: 2024-04-05 09:32:41 UTC
      stateChangeTime: 2024-04-05 09:32:39 UTC
      availableStorageSize: 2 GB
      Verify:  rg1-rn1: Storage directory on rg1-rn1 is running low
      [/var/kv/test1 size: 1 GB available: 1023 MB]
      Verify:  Rep Node [rg1-rn1]
      Status: RUNNING,MASTER sequenceNumber: 4,244 haPort: 5006
      availableStorageSize: 1023 MB storageType: HD
      serviceStartTime: 2024-04-05 09:32:52 UTC
      stateChangeTime: 2024-04-05 09:32:56 UTC

      Verification complete, 0 violations, 1 note found.
      Verification note: [rg1-rn1]
      Storage directory on rg1-rn1 is running low [/var/kv/test1
      size: 1 GB available: 1023 MB].

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

In this example you want to upgrade Oracle NoSQL Database from version 19.5.9 to version 24.1.11. Here `$KVHOME` is `/var/kv/kv-19.5.9` and `$KVROOT` is `/var/kv/kv-19.5.9/kvroot`.

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.*.* release and then upgrade it to 24.1.11.

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

In this example you are upgrading your Oracle NoSQL Database from version 22.1.7 to version 24.1.11. The data store has a capacity 1 and replication factor 2. You have two Storage Nodes in your data store. Here `$KVHOME` is `/var/kv/kv-22.1.7`, `$KVROOT` is `/var/kv/kv-22.1.7/kvroot` and `$KVHOST` is the hostname of your first Storage Node.

- 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(22.1.7). 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 #156
      150 partitions and 2 storage nodes
      Time: 2024-04-05 15:21:02 UTC   Version: 22.1.7
      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: 2 read-only: 0 offline: 0 maxDelayMillis: 1 maxCatchupTimeSecs: 0
      Storage Node [sn1] on <XX>.com: 5000
      Zone: [name=zone1 id=zn1 type=PRIMARY allowArbiters=false masterAffinity=false]
      Status: RUNNING   Ver: 22.1.7 2024-04-05 21:25:44 UTC  Build id: 477e7f102ab4
      Edition: Enterprise isMasterBalanced: true serviceStartTime: 2024-04-05 10:29:33 UTC
              Admin [admin1] Status: RUNNING,MASTER  serviceStartTime: 2024-04-05 10:29:44 UTC
              stateChangeTime: 2024-04-05 10:29:42 UTC availableStorageSize: 2 GB
              Rep Node [rg1-rn1] Status: RUNNING,MASTER sequenceNumber: 4,259 haPort: 5006
              availableStorageSize: 1023 MB storageType: HD
              serviceStartTime: 2024-04-05 10:29:56 UTC
              stateChangeTime: 2024-04-05 13:29:29 UTC
      Storage Node [sn2] on <XX>.com: 5000
      Zone: [name=zone1 id=zn1 type=PRIMARY allowArbiters=false masterAffinity=false]
      Status: RUNNING   Ver: 22.1.7 2024-04-05 21:25:44 UTC  Build id: 477e7f102ab4
      Edition: Enterprise  isMasterBalanced: true  serviceStartTime: 2024-04-05 13:29:18 UTC
              Admin [admin2] Status: RUNNING,REPLICA serviceStartTime: 2024-04-05 13:29:24 UTC
              stateChangeTime: 2024-04-05 13:29:23 UTC availableStorageSize: 2 GB
              Rep Node [rg1-rn2] Status: RUNNING,REPLICA sequenceNumber: 4,259 haPort: 5006
              availableStorageSize: 99 MB storageType: HD
              serviceStartTime: 2024-04-05 13:29:25 UTC
              stateChangeTime: 2024-04-05 13:29:29 UTC delayMillis: 1
              catchupTimeSecs: 0

- 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 #156
      150 partitions and 2 storage nodes
      Time: 2024-04-05 15:30:45 UTC   Version: 22.1.7
      See <XX>.com:/var/kv/kv-22.1.7/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: 22.1.7 2024-04-05 21:25:44 UTC  Build id: 477e7f102ab4
      Edition: Enterprise isMasterBalanced: true serviceStartTime: 2024-04-05 10:29:33 UTC

      Verify prerequisite: Storage Node [sn2] on <XX>.com: 5000
      Zone: [name=zone1 id=zn1 type=PRIMARY allowArbiters=false masterAffinity=false]
      Status: RUNNING   Ver: 22.1.7 2024-04-05 21:25:44 UTC  Build id: 477e7f102ab4
      Edition: Enterprise    isMasterBalanced: true
      serviceStartTime: 2024-04-05 13:29:18 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 (`22.1.7`).

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

- Restart the first Storage Node using the updated software release(`24.1.11`). Here `$NEW_KVHOME` is `/var/kv/kv-24.1.11` and `$KVROOT` is `/var/kv/kv-22.1.7/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

- 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 #156
      150 partitions and 2 storage nodes
      Time: 2024-04-05 10:35:44 UTC   Version: 24.1.11
      See <XX>.com:/var/kv/kv-22.1.7/kvroot/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: 24.1.11 2024-04-05 21:25:44 UTC  Build id: 477e7f102ab4
      Edition: Enterprise    isMasterBalanced: true
      serviceStartTime: 2024-04-05 10:29:33 UTC
      Verify: sn2: Node needs to be upgraded from 22.1.7 to version 24.1.11 or newer
      Verify upgrade: Storage Node [sn2] on <XX>.com: 5000
      Zone: [name=zone1 id=zn1 type=PRIMARY allowArbiters=false masterAffinity=false]
      Status: RUNNING   Ver: 22.1.7 2024-04-05 16:36:54 UTC  Build id: 61b68fb1a3ec
      Edition: Enterprise    isMasterBalanced: true
      serviceStartTime: 2024-04-05 10:18:09 UTC

      Verification complete, 0 violations, 1 note found.
      Verification note: [sn2]
      Node needs to be upgraded from 22.1.7 to version 24.1.11 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: 24.1.11,prerequisite: 20.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-24.1.11.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 (`22.1.7`).

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

- Restart the second Storage Node using the updated software release(`24.1.11`). Here `$NEW_KVHOME` is `/var/kv/kv-24.1.11` and `$KVROOT` is `/var/kv/kv-22.1.7/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. 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

- 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 #156
      150 partitions and 2 storage nodes
      Time: 2024-04-05 13:32:24 UTC   Version: 24.1.11
      See <XX>.com:/var/kv/kv-22.1.7/kvroot/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: 24.1.11 2024-04-05 21:25:44 UTC  Build id: 477e7f102ab4
      Edition: Enterprise    isMasterBalanced: true
      serviceStartTime: 2024-04-05 10:29:33 UTC
      Verify upgrade: Storage Node [sn2] on <XX>.com: 5000
      Zone: [name=zone1 id=zn1 type=PRIMARY allowArbiters=false masterAffinity=false]
      Status: RUNNING   Ver: 24.1.11 2024-04-05 21:25:44 UTC  Build id: 477e7f102ab4
      Edition: Enterprise    isMasterBalanced: true
      serviceStartTime: 2024-04-05 13:29:18 UTC

      Verification complete, no violations.

- Check if any other Storage Nodes need to be upgraded.

      kv-> show upgrade-order

      Calculating upgrade order, target version: 24.1.11,
      prerequisite: 20.1.12
      There are no nodes that need to be upgraded

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