Upgrading the Database Protocol

A new version of NuoDB database software may also introduce a new version of the database protocol. The database protocol cannot be upgraded until all Storage Manager (SM) and Transaction Engine (TE) processes have been upgraded to a software release which supports it. Once all processes are running a sufficiently new version of the software, NuoAdmin Command (nuocmd) can be used to upgrade the database protocol.

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 of the database hosts must have the new software version installed. If all of the existing database processes have not been upgraded to the new software version, the show database-versions command will show no available versions.

  1. Check whether a new database protocol is available.
    If no new database protocol is available then the upgrade is complete and the remaining steps are not needed.

  2. Upgrade the database protocol.

  3. Restart a Transaction Engine (TE) to finalize the protocol change.

Confirming Whether a new Database Protocol Version is Available

To determine whether a new database protocol version is available, run the show database-versions command; see NuoDB Command Reference.

If there is no new database protocol version available then nothing will be listed after Available versions: as shown here:

nuocmd show database-versions --db-name mydb
effective version ID: 1376256, effective version: 4.1|4.1.1|4.1.2, max version ID: 1376256
Available versions:
Process versions:
  ...

In this case the upgrade is complete and nothing more needs to be done.

When all processes are up-to-date with the latest version and there’s a new database protocol version available, it will be shown after Available versions: as shown here:

nuocmd show database-versions --db-name mydb
effective version ID: 1376256, effective version: 4.1|4.1.1|4.1.2, max version ID: 1376256
Available versions:
  version ID: 1441792, version: 4.2
Process versions:
  ...

In this case the database protocol needs to be updated, and the following steps should be taken.

Upgrading to a new Database Protocol

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

After the database protocol version has been upgraded, the NuoDB Archive cannot be used with NuoDB software versions that only support the previous database protocol version. As a result, downgrading after the database protocol version has been changed will require restoring a backup of the database. For more information on downgrading, see Downgrading to a Previous Release.

Upgrading to a Specific Version

To upgrade the database to a specific version, include the --version option. For example, to upgrade your database to NuoDB 4.0, run the following command:

nuocmd upgrade database-version --db-name mydb --version 4.2

Upgrading to the Latest Version Available

To upgrade the database to a specific version, include the --max-version option. For example:

nuocmd upgrade database-version --db-name mydb --max-version

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

To confirm that all processes have been upgraded to the latest version available, run the show database-versions command again.

nuocmd show database-versions --db-name mydb
effective version ID: 1441792, effective version: 4.2, max version ID: 1441792
Available versions:
Process versions:
  version ID: 1441792, version: 4.2, release: 4.2-1-c96c3d1a26
    [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

Restart a Transaction Engine

After the database protocol has been updated, a Transaction Engine (TE) must be restarted to perform final SQL operations related to the database protocol upgrade. You can determine whether or not a TE needs to be restarted by running this SQL query which will return YES if a TE restart is needed and NO otherwise:

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

If a TE restart is necessary, it’s simplest to restart an existing TE. Choose any TE in the database, and restart it using shutdown process then 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)