Upgrading your node to Corda 4.5

Corda releases strive to be backwards compatible, so upgrading a node is fairly straightforward and should not require changes to applications. It consists of the following steps:

• Drain the node.
• Make a backup of your node directories and/or database.
• Update the database.
• Replace the corda.jar file with the new version.
• Start up the node. (This step may incur a delay while any necessary database migrations are applied.)
• Undrain the node. (This step re-enables processing of new inbound flows.)

Step 1. Drain the node

Before a node, or an application on a node, can be upgraded, the node must be put in draining-mode. This brings the currently running Flows to a smooth halt (existing work is finished, and new work is queued rather than being processed).

Draining flows is a key task for node administrators to perform. It exists to simplify applications by ensuring apps don’t have to be able to migrate workflows from any arbitrary point to other arbitrary points, a task that would rapidly become unfeasible as workflow and protocol complexity increases.

To drain the node, run the gracefulShutdown command. This will wait for the node to drain and then shut it down once the drain is complete.

Step 2. Make a backup of your node directories and database

It’s always a good idea to back up your data before upgrading any server. This will make it easy to roll back if there’s a problem. You can simply make a copy of the node’s data directory to enable this. If you use an external non-H2 database, consult your database user guide to learn how to make backups.

For a detailed explanation of Corda backup and recovery guarantees, see Backup recommendations .

Step 3. Update database

This step is mandatory for production systems.

You can also skip the manual database update and allow a Corda node to auto-update its database on startup when:

• A database setup is for testing/development purposes and a Corda node connects with administrative permissions (it can modify database schema).
• You are upgrading a production system, however your policy allows a Corda node to auto-update its database and a Corda node connects with administrative permissions.

In both cases, start the node with the run-migration-scripts sub-command.

java -jar corda.jar run-migration-scripts

The node will perform any automatic data migrations required, which may take some time. If the migration process is interrupted it can be continued simply by starting the node again, without harm. The node will stop automatically when migration is complete.

3.1. Configure the Database Management Tool

The Corda Database Management Tool needs access to a running database. The tool is configured in a similar manner to the Corda node. A base directory needs to be provided with the following content:

• A node.conf file with database connection settings.
• A drivers directory (where the JDBC driver will be placed).

Create a node.conf with the properties for your database. node.conf templates for each database vendor are shown below.

Azure SQL

The required node.conf settings for the Database Management Tool using Azure SQL:

dataSourceProperties = {
    dataSourceClassName = "com.microsoft.sqlserver.jdbc.SQLServerDataSource"
    dataSource.url = "jdbc:sqlserver://<server>.database.windows.net:1433;databaseName=<database>;encrypt=true;trustServerCertificate=false;hostNameInCertificate=*.database.windows.net;loginTimeout=30"
    dataSource.user = <login>
    dataSource.password = <password>
}
database = {
    schema = <schema>
}
myLegalName = <node_legal_name>

Replace placeholders <server>, <login>, <password>, and <database> with appropriate values. <database> should be a user database and <schema> a schema namespace. Ensure <login> and <password> are for a database user with visibility of the <schema>. The myLegalName field is obligatory, however, it is used in Step 3.4 only (the tool doesn’t understand the context of the run and always requires the field to be present). For this step you can use any valid dummy name - for example, O=Dummy,L=London,C=GB for <node_legal_name>.

The Microsoft SQL JDBC driver can be downloaded from Microsoft Download Center. Extract the archive, and copy the single file mssql-jdbc-6.4.0.jre8.jar into the drivers directory.

SQL Server

The required node.conf settings for the Database Management Tool using SQL Server:

dataSourceProperties = {
    dataSourceClassName = "com.microsoft.sqlserver.jdbc.SQLServerDataSource"
    dataSource.url = "jdbc:sqlserver://<host>:1433;databaseName=<database>"
    dataSource.user = <login>
    dataSource.password = <password>
}
database = {
    schema = <schema>
}
myLegalName = <node_legal_name>

Replace placeholders <server>, <login>, <password>, <database> with appropriate values. <database> is a database name and <schema> is a schema namespace. Ensure <login> and <password> are for a database user with visibility of the <schema>. The myLegalName field is obligatory however it is used in Step 3.4 only (the tool doesn’t understand the context of the run and always requires the field to be present). For this step you can use any valid dummy name - for example, O=Dummy,L=London,C=GB for <node_legal_name>.

The Microsoft JDBC 6.4 driver can be downloaded from Microsoft Download Center. Extract the archive, and copy the single file mssql-jdbc-6.4.0.jre8.jar into the drivers directory.

Oracle

The required node.conf settings for the Database Management Tool using Oracle:

dataSourceProperties = {
    dataSourceClassName = "oracle.jdbc.pool.OracleDataSource"
    dataSource.url = "jdbc:oracle:thin:@<host>:<port>:<sid>"
    dataSource.user = <user>
    dataSource.password = <password>
}
database = {
    schema = <schema>
}
myLegalName = <node_legal_name>

Replace placeholders <host>, <port> and <sid>, <user>, <password> and <schema> with appropriate values. <schema> is a database schema namespace, for a basic setup the schema name equals <user>. The myLegalName field is obligatory however it is used in Step 3.4 only (the tool doesn’t understand the context of the run and always requires the field to be present). For this step you can use any valid dummy name - for example, O=Dummy,L=London,C=GB for <node_legal_name>.

Copy the Oracle JDBC driver ojdbc6.jar for 11g RC2 or ojdbc8.jar for Oracle 12c into the drivers directory.

PostgreSQL

The required node.conf settings for the Database Management Tool using PostgreSQL:

dataSourceProperties = {
    dataSourceClassName = "org.postgresql.ds.PGSimpleDataSource"
    dataSource.url = "jdbc:postgresql://<host>:<port>/<database>"
    dataSource.user = <user>
    dataSource.password = <password>
}
database = {
    schema = <schema>
}
myLegalName = <node_legal_name>

Replace placeholders <host>, <port>, <database>, <user>, <password> and <schema> with appropriate values. <schema> is the database schema name assigned to the user, the value of database.schema is automatically wrapped in double quotes to preserve case-sensitivity. The myLegalName field is obligatory however it is used in Step 3.4 only (the tool doesn’t understand the context of the run and always requires the field to be present). For this step you can use any valid dummy name - for example, O=Dummy,L=London,C=GB for <node_legal_name>.

Copy the PostgreSQL JDBC Driver 42.2.8 version JDBC 4.2 into the drivers directory.

3.2. Extract DDL script using Database Management Tool

To run the tool, use the following command:

java -jar tools-database-manager-|release|.jar dry-run -b path_to_configuration_directory

The option -b points to the base directory (which contains a node.conf file, and drivers and cordapps subdirectories).

A script named migrationYYYYMMDDHHMMSS.sql will be generated in the current directory. This script will contain all the statements required to modify and create data structures (for example, tables/indexes), and updates the Liquibase management table DATABASECHANGELOG. The command doesn’t alter any tables itself. For descriptions of the options, refer to the Corda Database Management Tool manual.

3.3. Apply DDL scripts on a database

The generated DDL script can be applied by the database administrator using their tooling of choice. The script needs to be run by a database user with administrative permissions, with a <schema> set as the default schema for that user and matching the schema used by a Corda node. (for example, for Azure SQL or SQL Server you should not use the default database administrator account).

3.4. Apply data updates on a database

The schema structure changes in Corda 4.0 require data to be propagated to new tables and columns based on the existing rows and specific node configuration (for example, node legal name). Such migrations cannot be expressed by the DDL script, so they need to be performed by the Database Management Tool (or a Corda node). These updates are required any time you are upgrading either from an earlier version to 4.0 or from 4.x to 4.x - for example, upgrading from 4.5 to 4.6.

The Database Management Tool can execute the remaining data upgrade. As the schema structure is already created in the 3rd step, the tool can connect with restricted database permissions. The only activities in this step are inserts/upgrades data rows, and no alterations to the schema are applied.

You can reuse the tool configuration directory (with modifications) created in Step 3.1, or you can run the tool accessing the base directory of a Corda node (for which the data update is being performed). In the latter case no configuration modification is needed, however the Database Migration Tool needs to be run from within the same machine as a Corda node runs.

If you are reusing the tool configuration directory:

1. Ensure myLegalName setting in node.conf is set with a node name for which the data update will be run (for example, while upgrading database schema used by a node O=PartyA,L=London,C=GB, assign the same value to myLegalName).

   Any node.conf misconfiguration may cause data row migration to be wrongly applied. This may happen silently (without any error). The value of myLegalName must exactly match the node name that is used in the given database schema.

2. Create cordapps subdirectory and copy the CorDapps used by the Corda node.

3. Change the database user to one with restricted permissions. This ensures no database alteration is performed by this step.To run the remaining data migration, run:

java -jar tools-database-manager-4.5-RC03.jar execute-migration -b .

The option -b points to the base directory (with a node.conf file, and drivers and cordapps subdirectories).

Step 4. Replace corda.jar with the new version

Replace the corda.jar with the latest version of Corda.

Download the latest version of Corda from our Artifactory site. Make sure it’s available on your path, and that you’ve read the Corda release notes. Pay particular attention to which version of Java this node requires.

Step 5. Start the node in the normal way

Start the node in the normal way.

Step 6. Undrain the node

You may now do any checks that you wish to perform, read the logs, and so on. When you are ready, use this command at the shell:

run setFlowsDrainingModeEnabled enabled: false

Your upgrade is complete.