Upgrading a node to Corda Enterprise Edition 4.12

Follow these steps to upgrade a node from Corda Enterprise Edition 4.x to Corda Enterprise Edition 4.12.

If you are upgrading from Corda Enterprise 3.x, you must first:

1. Upgrade your node to Corda Enterprise 3.3, if you haven’t already. If your node is running on an earlier version, follow the steps in Upgrade a Corda 3.X Enterprise Node (available in the archived-docs directory of the corda/corda-docs-portal repo).
2. Upgrade from Corda Enterprise 3.3 to Corda Enterprise Edition 4.5.
3. Upgrade from Corda 4.5 to Corda Enterprise Edition 4.11.
4. Upgrade from Corda 4.11 to Corda Enterprise Edition 4.12.

Most of the Corda 4 public, non-experimental APIs are stable. See the full list of stable APIs. If you are working with a stable API, you only need to follow the required CorDapp updates below. To upgrade:

1. Drain the node.
2. Make a backup of the directories in your node and database.
3. Update the database.
4. Replace the corda.jar file with the new version.
5. Update the configuration.
6. Validate existing transactions.
7. Update the CorDapps.
8. Create legacy folders.
9. Start the node.
10. Undrain the node.

Step 1: Drain the node

Node operators must drain nodes (or CorDapps on nodes) before they can upgrade them. Draining brings all flows that are currently running to a smooth halt. The node finishes any work already in progress, and queues any new work. This process frees CorDapps from the requirement to migrate workflows from an arbitrary point to another arbitrary point—a task that would rapidly become unfeasible as workflow and protocol complexity increases.

To drain a node, run gracefulShutdown. This waits for the all currently running flows to be completed and then shuts the node down.

Step 2: Make a backup of your node’s directories and database

Back up your data before upgrading, in case you need to roll back if there’s a problem. Make a copy of the node’s data directory or, 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 the database

The database update can be performed automatically or manually and must be performed incrementally for each major version. For example, if you are upgrading from version 4.9 to 4.12, you must first apply the database update from 4.9 to 4.10, and then apply the database update from 4.10 to 4.11, and then from 4.11 to 4.12. The minor version does not matter since there are no database updates contained in minor version releases.

You can perform an automatic database update when:

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

If you meet the above criteria, then skip steps 3.1 to 3.4 and go directly to Step 4. You’ll perform the automatic update in Step 6.

If you can’t perform an automatic update, then you must perform a manual update by following steps 3.1 to 3.4 below. You can then move on to Step 4.

3.1. Configure the Database Management Tool

The Corda Database Management Tool needs access to a running database. You set the tool up using a similar process to how you configure a node. You must provide a base directory that includes:

• A node.conf file with database connection settings.
• A drivers directory. You will place the JDBC driver here.

node.conf template files and details on where to find the JDBC driver for each database vendor can be found below.

Azure SQL: template file and JDBC driver

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

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>

1. Complete the template:

Replace the placeholders <server>, <database>, <login>, <password>, <schema>, and <node_legal_name>’ with appropriate values:

• <database> is the user database.
• <login> and <password> must be for a database user with visibility of the <schema>.
• <schema> is the schema namespace.
• myLegalName is mandatory. However, it is only used in Step 3.4. For this step you can replace <node_legal_name> with any valid dummy name, for example, O=Dummy,L=London,C=GB.

2. Download the Microsoft SQL JDBC driver from Microsoft Download Center.
3. Extract the archive and copy the single file mssql-jdbc-6.4.0.jre8.jar into the drivers directory.

SQL Server: template file and JDBC driver

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

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>

1. Complete the template:

Replace the placeholders <host>, <database>, <login>, <password>, <schema>, and <node_legal_name>’ with appropriate values:

• <database> is the user database.
• <login> and <password> must be for a database user with visibility of the <schema>.
• <schema> is the schema namespace.
• myLegalName is mandatory. However, it is only used in Step 3.4. For this step you can replace <node_legal_name> with any valid dummy name, for example, O=Dummy,L=London,C=GB.

2. Download the Microsoft JDBC 6.4 driver from Microsoft Download Center.
3. Extract the archive and copy the single file mssql-jdbc-6.4.0.jre8.jar into the drivers directory.

Oracle: template file and JDBC driver

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

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>

1. Complete the template:

Replace the placeholders <host>, <port>, <sid>, <user>, <password>, <schema>, and <node_legal_name>’ with appropriate values:

• <schema> is the database schema namespace. For a basic setup, the schema name equals <user>.
• myLegalName is mandatory. However, it is only used in Step 3.4. For this step you can replace <node_legal_name> with any valid dummy name, for example, O=Dummy,L=London,C=GB.

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

PostgreSQL: template file and JDBC driver

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

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>

1. Complete the template:

Replace the placeholders <host>, <port>, <database>, <user>, <password>, and <schema>, and <node_legal_name>’ 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.
• myLegalName is mandatory. However, it is only used in Step 3.4. For this step you can replace <node_legal_name> with any valid dummy name, for example, O=Dummy,L=London,C=GB.

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

3.2. Extract the DDL and DML scripts using the Database Management Tool

To run the tool, use the command:

java -jar tools-database-manager-<release number>.jar dry-run -b path_to_configuration_directory --core-schemas --app-schemas

Option -b points to the base directory. The directory contains a node.conf file and the drivers and cordapps subdirectories.

--core-schemas is required to adopt the changes made in the new version of Corda, and --app-schemas is related to the CorDapps changes.

A script named migrationYYYYMMDDHHMMSS.sql containing DDL and DML statements will be generated in the current directory. This script contains 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.

For more information about the Database Management Tool including available options and commands, see Corda Database Management Tool.

3.3. Apply DDL scripts to a database

The database administrator can apply the DDL scripts to the database using their tooling of choice. Then, any database user with administrative permissions, and whose default schema matches <schema> and the schema used by the node, can run the script. For example, for Azure SQL or SQL Server you should not use the default database administrator account.

You need to run the whole script. Partially running the script causes the database schema content to be inconsistently versioned.

3.4. Apply data updates on the H2 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 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, if you’re upgrading from 4.5 to 4.11.

The Database Management Tool can execute the remaining data upgrade. The tool can connect with restricted database permissions as the schema structure was created in step three. In this step, you will insert and upgrade the data rows. This process does not alter the schema.

You can modify and reuse the tool configuration directory you created in Step 3.1, or you can run the tool by accessing the base directory of the node you are updating. If you choose to update the data by accessing the base directory, you do not need to modify the tool configuration. However, you must run the tool from the same machine the node is running on.

If you are reusing the tool configuration directory:

1. Set the myLegalName setting in node.conf to the name of the node you are running the data update for. For example, if you are upgrading the database schema used by node O=PartyA,L=London,C=GB, assign the same value to myLegalName.

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

3. Change the database user to one with restricted permissions. This ensures the database cannot be altered. To complete the data migration, run:

java -jar tools-database-manager-4.11.jar execute-migration -b . --core-schemas --app-schemas

Option -b points to the base directory which contains a node.conf file and drivers and cordapps subdirectories.

--core-schemas is required to adopt the changes made in the new version of Corda, and --app-schemas is related to the CorDapps changes.

Step 4: Replace corda.jar with the new version

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

Download the latest version of Corda from Maven. 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 the node requires.

Step 5: Update the configuration

Remove any transactionIsolationLevel, initialiseSchema, or initialiseAppSchema entries from the database section of your configuration.

Step 6: Validate existing transactions

Run the Transaction Validator Utility (TVU) to ensure that existing transactions are compatible with 4.12, see Validate transactions for more information.

Step 7: Update the CorDapps

When upgrading from Corda 4.11 to Corda 4.12 there are specific changes that need to be made to the CorDapps contract version and minimum platform version (MPV), see Upgrade 4.11 CorDapps for more information.

Step 8: Create legacy folders

When upgrading to 4.12 and the network contains a mix of 4.12 and pre-4.12 nodes, you must create a legacy-contracts folder and, if required, a legacy-jars folder. See Corda Enterprise Edition 4.11 to 4.12 upgrade guide for details.

Step 9: Start the node

If you manually updated the database in Step 3, start the node in the normal way.

However, if you need to automatically update the database as described in Step 3, then you need to start your node using the command:

java -jar corda.jar run-migration-scripts --core-schemas --app-schemas

The node will perform any automatic data migrations required, which may take some time. If the migration process is interrupted, restart the node to continue. The node stops automatically when migration is complete.

Step 10: Undrain the node

Run this command in the shell:

run setFlowsDrainingModeEnabled enabled: false

Your upgrade is complete.

Notes