Upgrade the Database Protocol

A new version of NuoDB database software may also introduce a new version of the database protocol. The database protocol is an agreed-upon protocol that the Storage Manager (SM) and Transaction Engine (TE) use to communicate with each other and store data on disk. Since NuoDB supports rolling upgrades, SMs or TEs running a newer software version may use an older database protocol to communicate with SMs and TEs running an older software version. Some new features may be locked behind a new database protocol and are only enabled once the database protocol is upgraded. To enable these new features, upgrade all SMs and TEs to a software release that supports the protocol and then upgrade the database protocol using NuoDB Command (nuocmd).

If a new database protocol is available, the database is not fully upgraded until the database protocol has been upgraded.

Before the database protocol can be upgraded, all database hosts must have installed the new software version.

To upgrade the database protocol, follow these steps.

Check whether a new database protocol is available.
To determine whether a new database protocol version is available, run nuocmd show database-versions. For more information, see the show database-versions command.

New database protocol version is not available

If the Available versions is empty, there is no new database protocol version available. For example:

nuocmd show database-versions --db-name mydb

effective version ID: 1441792, effective version: 4.2|4.2.1|4.2.2|4.2.3|4.2.4|4.2.5|4.2.6|4.2.7, max version ID: 1441792
Available versions:
Process versions:
  version ID: 1507328, version: 4.2|4.2.1|4.2.2|4.2.3|4.2.4|4.2.5|4.2.6|4.2.7, release: 4.2.7-e794a691fc
    [SM] sm-mydb-nuodb-cluster0-mydb-database-0/10.1.0.236:48006 [start_id = 0] [server_id = admin-nuodb-cluster0-0] [pid = 152] [node_id = 1] [last_ack =  3.47] MONITORED:RUNNING
    [TE] te-mydb-nuodb-cluster0-mydb-database-67df8bd-hvdfc/10.1.0.235:48006 [start_id = 1] [server_id = admin-nuodb-cluster0-0] [pid = 98] [node_id = 2] [last_ack =  6.30] MONITORED:RUNNING

In this case, the upgrade is complete. Skip the remaining steps.

New database protocol version is available

When all processes are up-to-date with the latest version and there is a new database protocol version available, it is listed as Available versions.
For example:

nuocmd show database-versions --db-name mydb

effective version ID: 1376256, effective version: 4.2|4.2.1|4.2.2|4.2.3|4.2.4|4.2.5|4.2.6|4.2.7, max version ID: 1376256
Available versions:
  version ID: 1441792, version: 4.3
Process versions:
  version ID: 1507328, version: 4.2|4.2.1|4.2.2|4.2.3|4.2.4|4.2.5|4.2.6|4.2.7, release: 4.2.7-e794a691fc
    [SM] sm-mydb-nuodb-cluster0-mydb-database-0/10.1.0.236:48006 [start_id = 0] [server_id = admin-nuodb-cluster0-0] [pid = 152] [node_id = 1] [last_ack =  3.47] MONITORED:RUNNING
    [TE] te-mydb-nuodb-cluster0-mydb-database-67df8bd-hvdfc/10.1.0.235:48006 [start_id = 1] [server_id = admin-nuodb-cluster0-0] [pid = 98] [node_id = 2] [last_ack =  6.30] MONITORED:RUNNING

In this case, proceed to Upgrade the database protocol.

Upgrade the database protocol.

To upgrade to a new database protocol, run nuocmd upgrade database-version.

After upgrading the database protocol version, the NuoDB Archive cannot be used with NuoDB software versions that only support the previous database protocol version. As a result, downgrading after changing the database protocol version requires restoring a backup of the database. For more information on downgrading, see Downgrade to a Previous Release.

Upgrade to a specific NuoDB version
To upgrade the database to a specific version, run nuocmd upgrade database-version with the --version option. For example, to upgrade your database to NuoDB 5.0, run the following command.
nuocmd upgrade database-version --db-name <database_name> --version 5.0

Upgrade to the latest NuoDB version

To upgrade the database to the latest version, run nuocmd upgrade database-version with the --max-version option. For example, to upgrade your database to the latest NuoDB version, run the following command.

nuocmd upgrade database-version --db-name <database_name> --max-version

Unless there is an error, nuocmd upgrade database-version generates no output.

To check whether all processes are upgraded to the latest version available, run nuocmd show database-versions again.

nuocmd show database-versions --db-name mydb

effective version ID: 1507328, effective version: 4.3|4.3.1|4.3.2, max version ID: 1507328
Available versions:
Process versions:
  version ID: 1507328, version: 4.3|4.3.1|4.3.2, release: 4.3.2-1-a69794e1fc
    [SM] sm-demo-nuodb-cluster0-demo-database-0/10.1.0.236:48006 [start_id = 0] [server_id = admin-nuodb-cluster0-0] [pid = 152] [node_id = 1] [last_ack =  3.47] MONITORED:RUNNING
    [TE] te-demo-nuodb-cluster0-demo-database-67df8bd-hvdfc/10.1.0.235:48006 [start_id = 1] [server_id = admin-nuodb-cluster0-0] [pid = 98] [node_id = 2] [last_ack =  6.30] MONITORED:RUNNING

Restart a TE to finalize the protocol change.

After updating the database protocol, restart the TE to perform the final SQL operations related to the database protocol upgrade. To check whether a TE needs to be restarted, run the following SQL query.

select case when version = GETEFFECTIVEPLATFORMVERSION() then 'NO' else 'YES' end
    as NEED_TE_RESTART_FOR_UPGRADE from system.versions
    where property = 'SYSTEM_TABLES_VERSION';

 NEED_TE_RESTART_FOR_UPGRADE
 ----------------------------
            YES

It returns a YES if a TE restart is required and a NO otherwise. If a TE restart is required, restart an existing TE using nuocmd shutdown process and nuocmd start process.

nuocmd show database --db-name mydb --skip-exited

Database(default_options={}, default_region_id=0, incarnation=(1, 1), name=test, server_assignments={}, state=RUNNING)
  mydb [state = RUNNING]
    [SM] host1:48006 [start_id = 5] [server_id = nuoadmin-0] [pid = 25439] [node_id = 6] [last_ack =  4.12] MONITORED:RUNNING
    [SM] host2:48006 [start_id = 6] [server_id = nuoadmin-1] [pid = 65232] [node_id = 7] [last_ack =  3.76] MONITORED:RUNNING
    [TE] host3:48006 [start_id = 7] [server_id = nuoadmin-2] [pid = 86244] [node_id = 8] [last_ack =  5.43] MONITORED:RUNNING
    [TE] host4:48006 [start_id = 4] [server_id = nuoadmin-3] [pid = 82572] [node_id = 5] [last_ack =  2.11] MONITORED:RUNNING

nuocmd shutdown process --start-id 7

nuocmd start process --db-name mydb --server-id nuoadmin-2 --engine-type TE

Process(db_name=mydb, durable_state=REQUESTED, engine_state=UNKNOWN, engine_type=TE, ipVersion=v4, labels={},
    options={log-over-conn: enable, database: mydb, region-name: Default, engine-type: TE, geo-region: 0, commit: safe},
    region_name=Default, server_id=nuoadmin-2, start_id=8)