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:
- 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).
- Upgrade from Corda Enterprise 3.3 to Corda Enterprise Edition 4.5.
- Upgrade from Corda 4.5 to Corda Enterprise Edition 4.11.
- 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:
- Drain the node.
- Make a backup of the directories in your node and database.
- Update the database.
- Replace the corda.jar file with the new version.
- Update the configuration.
- Validate existing transactions.
- Update the CorDapps.
- Start the node.
- Undrain the node.
Step 1: Drain the node
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
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.
The length of time a node takes to drain varies. It depends on how your CorDapps are designed and whether any CorDapps are communicating with network peers that are offline or slow to respond. If the CorDapps are well-written and the required counterparties are online, drains may only take a few seconds.
For a smooth node draining process avoid long-running flows.
Step 2: Make a backup of your node’s directories and database
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
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
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
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
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
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
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
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>
- 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
.
- Download the Microsoft SQL JDBC driver from Microsoft Download Center.
- Extract the archive and copy the single file
mssql-jdbc-6.4.0.jre8.jar
into thedrivers
directory.
SQL Server: template file and JDBC driver
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
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>
- 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
.
- Download the Microsoft JDBC 6.4 driver from Microsoft Download Center.
- Extract the archive and copy the single file
mssql-jdbc-6.4.0.jre8.jar
into thedrivers
directory.
Oracle: template file and JDBC driver
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
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>
- 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
.
- Copy the Oracle JDBC driver
ojdbc6.jar
for 11g RC2 orojdbc8.jar
for Oracle 12c into thedrivers
directory.
PostgreSQL: template file and JDBC driver
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
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>
- 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
.
- 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
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
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
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
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
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
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:
- Set the
myLegalName
setting innode.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 nodeO=PartyA,L=London,C=GB
, assign the same value tomyLegalName
.
myLegalName
must exactly match the node name used in the database schema. Any node.conf
misconfiguration may cause data row migration to be wrongly applied. This may happen silently, without throwing an error.Create a
cordapps
subdirectory and copy the CorDapps used by the node.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
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
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
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
Remove any transactionIsolationLevel
, initialiseSchema
, or initialiseAppSchema
entries from the database section of your configuration.
Step 6: Validate existing transactions
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
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
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
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: Start the node
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
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 9: Undrain the node
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
Run this command in the shell:
run setFlowsDrainingModeEnabled enabled: false
Your upgrade is complete.
Notes
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
Was this page helpful?
Thanks for your feedback!
Chat with us
Chat with us on our #docs channel on slack. You can also join a lot of other slack channels there and have access to 1-on-1 communication with members of the R3 team and the online community.
Propose documentation improvements directly
Help us to improve the docs by contributing directly. It's simple - just fork this repository and raise a PR of your own - R3's Technical Writers will review it and apply the relevant suggestions.
We're sorry this page wasn't helpful. Let us know how we can make it better!
Chat with us
Chat with us on our #docs channel on slack. You can also join a lot of other slack channels there and have access to 1-on-1 communication with members of the R3 team and the online community.
Create an issue
Create a new GitHub issue in this repository - submit technical feedback, draw attention to a potential documentation bug, or share ideas for improvement and general feedback.
Propose documentation improvements directly
Help us to improve the docs by contributing directly. It's simple - just fork this repository and raise a PR of your own - R3's Technical Writers will review it and apply the relevant suggestions.