Post-Upgrade Procedure

Learn how to perform the post-upgrade procedure to maintain system compatibility.

The post-upgrade procedure advances the data store’s system compatibility version and enables new features such as row creation time and user-supplied metadata. This maintains system compatibility as you deploy applications that use these new features. You must run the post-upgrade procedure soon after upgrading the data store and its associated components.

Prerequisites:

All the Storage Nodes in the data store are upgraded to the specified release.
If your data store includes the following components, ensure they are upgraded to the specified release.

Oracle NoSQL Database Proxy, direct drivers, SDKs, and XRegion agents.

Perform the following steps:

Run the plan upgrade-scv command from the Admin cli.

kv-> plan upgrade-scv -version 26.1

You will see an output similar to:

Started plan 37. Use show plan -id 37 to check status.
    To wait for completion, use plan wait -id 37

To view the status:

kv-> show plan -id 37

Plan SCVState plan
Owner:                 root(id:u1)

Id:                    37
State:                 SUCCEEDED
Attempt number:        1
Started:               2026-02-11 05:24:02 UTC
Ended:                 2026-02-11 05:24:03 UTC
Total tasks:           1
 Progress percent:     100
 Successful:           1

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

kv-> verify configuration

Sample output:

Verify: starting verification of store mystore based upon topology sequence #154
150 partitions and 1 storage nodes
Time: 2026-02-11 05:24:51 UTC   Version: 26.1.x
See localhost:kvhome/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:         sn1: The root directory on sn1 does not have a size specified: kvhome/kvroot
Verify: 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-01-30 12:08:58 UTC
Verify:     Admin [admin1]        Status: RUNNING,MASTER    serviceStartTime: 2026-01-30 12:09:13 UTC    stateChangeTime: 2026-01-30 12:09:12 UTC    availableStorageSize: 2 GB
Verify:     Rep Node [rg1-rn1]    Status: RUNNING,MASTER sequenceNumber: 206,729 haPort: 5006 availableStorageSize: 336 GB storageType: HD    serviceStartTime: 2026-01-30 12:09:16 UTC    stateChangeTime: 2026-01-30 12:09:20 UTC

Verification complete, 0 violations, 1 note found.
Verification note: [sn1]    The root directory on sn1 does not have a size specified: kvhome/kvroot

Note:

Use new features only after enabling them with the plan upgrade-scv command to avoid any exceptions by incompatibility issues.
You can run the plan upgrade-scv command only after the data store has been upgraded to the version specified in the command. If you run it before upgrading the store, the system returns an IllegalCommandException because the store's version is not yet supported. For example:
```
 oracle.kv.impl.admin.IllegalCommandException:version 30.5 is not supported
```
The plan upgrade-scv command requires the data store to be fully healthy to complete successfully. If the plan fails or times out, appropriate error messages are displayed indicating issues in the data store. The plan also checks the data store's internal state for any incompatibilities, which if detected, will result in plan failure. It is recommended to investigate, fix the issues, and re-run the plan.

If you don't run the plan upgrade-scv command, the verify upgrade and verify configuration commands will display incompatibility status notes similar to:

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.

It is recommended to avoid topology/elasticity operations until the plan upgrade-scv completes successfully.
When upgrading to Release 26.1 from a prior release, extra care must be taken to ensure that all regions in a multi-region setup are upgraded before using the User-supplied metadata feature, which is enabled through the System Compatibility Version (SCV) upgrade procedure (post-upgrade procedure) outlined above. Failure to do so may cause a region running an older version of the MR agent to fail when attempting to read data containing the explicit user-supplied metadata introduced in the 26.1 release.