1. Administrator's Guide
  2. Install and Upgrade
  3. Upgrading an Existing Oracle NoSQL Database Deployment
  4. Steps to Upgrade - Examples

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 23.1.21. 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
Pinging components of store mystore based upon topology sequence #154
150 partitions and 1 storage nodes
Time: 2023-07-14 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:  2023-07-14 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

Verify: starting verification of store mystore based upon topology sequence #154
150 partitions and 1 storage nodes
Time: 2023-07-17 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 2022-02-15 16:36:54 UTC  Build id: 61b68fb1a3ec 
Edition: Enterprise    isMasterBalanced: true 
serviceStartTime: 2023-07-17 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(23.1.21). Here $NEW_KVHOME is /var/kv/kv-23.1.21 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
Verify: starting verification of store mystore based upon topology sequence #154
150 partitions and 1 storage nodes
Time: 2023-07-17 09:33:10 UTC   Version: 23.1.21
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: 23.1.21 2023-04-18 21:25:44 UTC  Build id: 477e7f102ab4 
Edition: Enterprise    isMasterBalanced: true     
serviceStartTime: 2023-07-17 09:32:29 UTC
Verify:         Admin [admin1]          
Status: RUNNING,MASTER  serviceStartTime: 2023-07-17 09:32:41 UTC       
stateChangeTime: 2023-07-17 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: 2023-07-17 09:32:52 UTC       
stateChangeTime: 2023-07-17 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 23.1.21. 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 23.1.21.
  • 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(23.1.21).
    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-23.1.21/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 23.1.21 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 23.1.21.

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 23.1.21. 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

Pinging components of store mystore based upon topology sequence #156
150 partitions and 2 storage nodes
Time: 2023-07-17 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 2023-04-18 21:25:44 UTC  Build id: 477e7f102ab4 
Edition: Enterprise isMasterBalanced: true serviceStartTime: 2023-07-17 10:29:33 UTC
        Admin [admin1] Status: RUNNING,MASTER  serviceStartTime: 2023-07-17 10:29:44 UTC
        stateChangeTime: 2023-07-17 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: 2023-07-17 10:29:56 UTC  
        stateChangeTime: 2023-07-17 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 2023-04-18 21:25:44 UTC  Build id: 477e7f102ab4 
Edition: Enterprise  isMasterBalanced: true  serviceStartTime: 2023-07-17 13:29:18 UTC
        Admin [admin2] Status: RUNNING,REPLICA serviceStartTime: 2023-07-17 13:29:24 UTC
        stateChangeTime: 2023-07-17 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: 2023-07-17 13:29:25 UTC  
        stateChangeTime: 2023-07-17 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

Verify: starting verification of store mystore based upon topology sequence #156
150 partitions and 2 storage nodes
Time: 2023-07-17 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 2023-04-18 21:25:44 UTC  Build id: 477e7f102ab4 
Edition: Enterprise isMasterBalanced: true serviceStartTime: 2023-07-17 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 2023-04-18 21:25:44 UTC  Build id: 477e7f102ab4 
Edition: Enterprise    isMasterBalanced: true   
serviceStartTime: 2023-07-17 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(23.1.21). Here $NEW_KVHOME is /var/kv/kv-23.1.21 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
Verify: starting verification of store mystore based upon topology sequence #156
150 partitions and 2 storage nodes
Time: 2023-07-17 10:35:44 UTC   Version: 23.1.21
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: 23.1.21 2023-04-18 21:25:44 UTC  Build id: 477e7f102ab4 
Edition: Enterprise    isMasterBalanced: true 
serviceStartTime: 2023-07-17 10:29:33 UTC
Verify: sn2: Node needs to be upgraded from 22.1.7 to version 23.1.21 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 2022-02-15 16:36:54 UTC  Build id: 61b68fb1a3ec 
Edition: Enterprise    isMasterBalanced: true 
serviceStartTime: 2023-07-17 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 23.1.21 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
Calculating upgrade order,target version: 23.1.21,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-23.1.21.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(23.1.21). Here $NEW_KVHOME is /var/kv/kv-23.1.21 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
Verify: starting verification of store mystore based upon topology sequence #156
150 partitions and 2 storage nodes
Time: 2023-07-17 13:32:24 UTC   Version: 23.1.21
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: 23.1.21 2023-04-18 21:25:44 UTC  Build id: 477e7f102ab4 
Edition: Enterprise    isMasterBalanced: true    
serviceStartTime: 2023-07-17 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: 23.1.21 2023-04-18 21:25:44 UTC  Build id: 477e7f102ab4 
Edition: Enterprise    isMasterBalanced: true   
serviceStartTime: 2023-07-17 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: 23.1.21,
prerequisite: 20.1.12
There are no nodes that need to be upgraded
    The output shows the upgrade for all Storage Nodes is complete.