Continuing Database Harmonization Between Corda and Corda Enterprise
Since our Corda Enterprise launch in July of 2018, it's been our goal that CorDapps written and tested on Corda should work seamlessly when migrated to Corda Enterprise, without additional effort needed. With the release of Corda 4.6, we’ve added new enhancements to database harmonization to instill confidence in CorDapp developers that their CorDapps will work, no matter which flavor of Corda they choose.
In this blog, we will cover the database improvements included in the latest release to achieve easier harmonization and what steps should be taken by CorDapp developers interested in migrating to Corda 4.6.
First, a bit on Liquibase
Both the internals of the Corda and external enterprise CorDapps use Liquibase for database schema versioning. CorDapp custom tables are created or upgraded automatically using Liquibase. Liquibase supports writing DDL/DML statements in many formats (XML, JSON, SQL, YAML).
How does Liquibase work?
Liquibase uses a table called as DATABASECHANGELOG. This table maintains all the executed/applied DDL/DML scripts till date. Liquibase uses something called changeset to save executed scripts in DATABASECHANGELOG table. Each changeset is a collection of DDL/DML scripts. Essentially, DATABASECHANGELOG stores each executed changeset. This changelog table will be read every time a migration command is run to determine what changesets need to be executed. The node by default uses Liquibase internally which can be verified by looking at node-specific changesets in the DATABASECHANGELOG table. Liquibase will also be used by the CorDapp developer for CorDapp custom schemas. So each time a new schema is introduced, a new liquibase script should be added to the CorDapp.
Changes introduced in Corda 4.6
In Corda, Liquibase was not supported/needed till now, and custom schemas/tables were created using Hibernate JPA. The idea is to harmonize database schema creation using Liquibase across Corda and Corda Enterprise. With this approach, migration scripts will now be needed for Corda as well. Migrating from Corda to Corda Enterprise will now be easy and will increase the possibility of discovering bugs/ testing migration scripts at a very early stage. Before Corda 4.6, nodes were setting up their schemas at runtime, whereas now, schema management is a deliberate step that has to be taken before running.
1. run-migration-scripts
2. — allow-hibernate-to-manage-app-schemas
3. runSchemaMigration = true
4. transactionIsolationLevel , initialiseSchema, initialiseAppSchema — These flags have now been removed and can no longer be used.
Upgrade from lower versions to Corda 4.6
CorDapp Upgrade
As mentioned above, until now, migration scripts/Liquibase were not required in open source. Hence any custom tables present in your CorDapp were created by Hibernate. Since Liquibase was not used to create these tables, there won't be any entries in the databasechangelog table. So, we will have to add these entries to the databasechangelog retrospectively. Follow the below steps to upgrade your CorDapp.
Assumption: The CorDapp is using a version of Corda less than 4.6.
Custom schemas/tables have been created in the database using Hibernate. There are no databasechangelog entries corresponding to this schema. I will be using the cordapp-example to perform a CorDapp upgrade to 4.6.
Step 1. Define Liquibase Scripts
Step 2. Override Migration resource by specifying the migration script name
Step 3. Place the migration scripts in resources/migration folder in workflow
Step 4. Build workflow and contract jar.
Command: “./gradlew jar” to be run from project root. The cordapp jars can be found in build/libs directory of workflow and contract respectively.
Step 5. Replace old workflow and contract jar with new one.
Step 6. Start the node by running java -jar corda.jar sync-app-schemas.
If you do not run the sync-app-schemas and instead directly run run-migration-scripts — app-schemas command, it will complain with below error.
This is because we already have a table created by Hibernate in the database. To sync migration entry to databasechangelog use sync-app-schemas command. This will sync the table created by Hibernate and an entry will be made in the databasechangelog using the migration scripts.
Step 7. Start the node
Node Upgrade
By default, the node uses Liquibase scripts internally for its tables. Assuming all the required tables before 4.6 must be present in the database; we only need to worry about adding the new core schema tables part of 4.6.
Step 1. Stop the node. Replace corda.jar with new 4.6 corda.jar
Step 2. Run the command run-migration-scripts — core-schemas to run new schemas part of 4.6. Running this command will automatically apply the new Liquibase scripts onto the database.
Step 3. Start the node.
Upgrade from versions Corda >= 4.6 to Corda Enterprise >= 4.6
CorDapp developers upgrading from an older version of Corda or Corda Enterprise to 4.6 will only need to run one command to upgrade the node.
CorDapp Upgrade
Note: If switching from H2 to any other database, users are required to retrospectively add entries to databasechangelog table for the custom tables created by Hibernate in Open Source.
As explained above, when upgrading from Corda to Corda Enterprise, developers are required to add Liquibase scripts for their CorDapps. Now developers won’t be required to add any Liquibase script for Enterprise, as they would already have a Liquibase script for our CorDapp in Corda. In addition, syncing changelogs will not be required.
Hence from an Corda to Corda Enterprise upgrade perspective, users don’t have to do anything beyond replacing the Corda jar with a Corda Enterprise jar!
Node Upgrade
Node upgrade will require adding extra tables/schemas of Corda Enterprise by running the below command.
java -jar corda.jar run-migration-scripts -core-schemas
Note: All the above migration paths apply to Corda 4.x nodes only and not to any of 3.x Corda nodes.
Summary
With the 4.6 release, database schemas are harmonized across Corda and Corda Enterprise by removing all schema management options from node configuration files and added start-up sub-commands. This would help reduce error-prone node configs. Liquibase support has now been added to Corda, making the upgrade from Corda to Corda Enterprise that much easier for CorDapp developers.
Thank you to Christian Sailer, Valerio Campanella, and the Corda Team.
Thanks for reading — Sneha Damle, Developer Evangelist (R3)
Want to learn more about building excellent blockchain applications on Corda? Be sure to visit corda.net, check out our community page to learn how to connect with other Corda developers, and sign up for one of our newsletters for the latest updates.
