Upgrading your node to Corda 4
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 database
- Replace the
corda.jarfile with the new version.
- Start up the node. This step may incur a delay whilst any needed database migrations are applied.
- Undrain it to re-enable processing of new inbound flows.
The protocol is designed to tolerate node outages, so during the upgrade process peers on the network will wait for your node to come back.
Step 1. Drain the node
Before a node or application on it can be upgraded, the node must be put in Draining mode. This brings the currently running Flows to a smooth halt such that existing work is finished and new work is queuing up 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 infeasible 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 down the node when the drain
Step 2. Make a backup of your node directories and/or database
It’s always a good idea to make a backup of 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 please consult your database user guide to learn how to make backups.
Please see Backup recommendations for a detailed explanation of Corda backup and recovery guarantees.
Step 3. Update database
Upgrading to Corda 4 from Corda 3.x requires both schema and data updates.
If using the development H2 database, there is no need to perform any explicit upgrade steps if schema changes are additive (e.g. new tables, columns, indexes).
Simply restart the node with the upgraded
corda.jar and the H2 database will be updated automatically.
However, if schema changes are non-additive (e.g. modification or removal of tables, columns) the user is responsible for manually adjusting
the H2 schema to reflect these changes (and perform any data copying as required).
If using an Enterprise grade commercial database you have two options:
- Use the Corda Database management tool to generate and execute SQL upgrade scripts.Generate the scripts by running the following command:
java -jar corda-tools-database-manager-4.0.jar –base-directory /path/to/node –dry-run
The generated scripts should then be applied by your database administrator using their tooling of choice or by executing the following command:
java -jar corda-tools-database-manager-4.0.jar –base-directory /path/to/node –execute-migration
Restart the node with the upgraded
- Configure the node to automatically execute all database SQL scripts upon startup.
This requires setting the following flag in the node’s associated
database.runMigration = true
See Backup Recommendations for further information.
Please refer to Database schema setup for detailed instructions.
This release requires some data migration to populate new entities.
DDL script execution and automatic data update by a database administrator using the Corda Database management tool.Follow the steps described here. This upgrade procedure is a mix of running the DDL script for schema update and running Database management tool for non-schema alteration changes. All steps of this procedure except the first one needed to be run:Extract DDL script using :ref:
Database management tool <migration-tool>Apply DDL scripts on a database *Apply remaining data upgrades on a database.*Note the last step is important because Corda 4 contains new columns/tables which needed to be populated based on your existing data, and these migration can’t be expressed in DDL script.Specifically, the
vault_statestable adds the following:>
state_partytable (and new fields)
and uses some custom migration code (executed as a custom change set by Liquibase) to achieve this. In order to determine if a state is relevant
for a node, the migration code needs to know the nodes name, which it obtains from
myLegalName (set in the Database management tool configuration file).
The migration code also requires access to the node’s CorDapps in order to understand which custom
MappedSchema objects to process.>
* If you are not reusing a node base directory, copy any CorDapps from a node being upgraded to *cordapps* subdirectory accessed by the tool.
Step 4. Replace
corda.jar with the new version
Download the latest version of Corda from our Artifactory site. Make sure it’s available on your path, and that you’ve read the Release notes for Corda 4, in particular to discover what version of Java this node requires.
Step 5. Start up the node
Start the node in the usual manner you have selected. 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.
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.