diff --git a/docs/source/corda-nodes-index.rst b/docs/source/corda-nodes-index.rst index 4c8c346c11..85b00fcc1c 100644 --- a/docs/source/corda-nodes-index.rst +++ b/docs/source/corda-nodes-index.rst @@ -14,4 +14,5 @@ Nodes node-database node-administration node-operations-upgrading + node-operations-upgrade-cordapps out-of-process-verification \ No newline at end of file diff --git a/docs/source/node-operations-upgrade-cordapps.rst b/docs/source/node-operations-upgrade-cordapps.rst new file mode 100644 index 0000000000..3da2d7ebd3 --- /dev/null +++ b/docs/source/node-operations-upgrade-cordapps.rst @@ -0,0 +1,71 @@ +Upgrading CorDapps on a node +============================ + +In order to upgrade a CorDapp on a node to a new version, it needs to be determined whether any backwards compatible +changes have been made. These could range from database changes, to changes in the protocol. + +For developer information on upgrading CorDapps, see :doc:`upgrading-cordapps`. + +To be compatible with Corda Enterprise, CorDapps need to bundle database migaration scripts (see :doc:`database-management`). + + +Flow upgrades +~~~~~~~~~~~~~ + +If any backwards-incompatible changes have been made (see :ref:`upgrading-cordapps-backwards-incompatible-flow-changes` +for more information), the upgrade method detailed below will need to be followed. Otherwise the CorDapp JAR can just +be replaced with the new version. + +Contract and State upgrades +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +There are two types of contract/state upgrade: + +1. *Implicit:* By allowing multiple implementations of the contract ahead of time, using constraints. See + :doc:`api-contract-constraints` to learn more. +2. *Explicit:* By creating a special *contract upgrade transaction* and getting all participants of a state to sign it using the + contract upgrade flows. + +This documentation only considers the *explicit* type of upgrade, as implicit contract upgrades are handled by the application. + +In an explicit upgrade contracts and states can be changed in arbitrary ways, if and only if all of the state's participants +agree to the proposed upgrade. The following combinations of upgrades are possible: + +* A contract is upgraded while the state definition remains the same. +* A state is upgraded while the contract stays the same. +* The state and the contract are updated simultaneously. + +Running the upgrade +~~~~~~~~~~~~~~~~~~~ + +If a contract or state requires an explicit upgrade then all states will need updating to the new contract at a time agreed +by all participants. The updated CorDapp JAR needs to be distributed to all relevant parties in advance of the changeover +time. + +In order to perform the upgrade, follow the following steps: + +* If required, do a flow drain to avoid the definition of states or contracts changing whilst a flow is in progress (see :ref:`upgrading-cordapps-flow-drains` for more information) + + * By RPC using the ``setFlowsDrainingModeEnabled`` method with the parameter ``true`` + * Via the shell by issuing the following command ``run setFlowsDrainingModeEnabled enabled: true`` + +* Check that all the flows have completed + + * By RPC using the ``stateMachinesSnapshot`` method and checking that there are no results + * Via the shell by issuing the following command ``run stateMachinesSnapshot`` + +* Once all flows have completed, stop the node +* Replace the existing JAR with the new one +* Make any database changes required to any custom vault tables for the upgraded CorDapp +* Restart the node +* If you drained the node prior to upgrading, switch off flow draining mode to allow the node to continue to receive requests + + * By RPC using the ``setFlowsDrainingModeEnabled`` method with the parameter ``false`` + * Via the shell by issuing the following command ``run setFlowsDrainingModeEnabled enabled: false`` + +* Run the contract upgrade authorisation flow (``ContractUpgradeFlow$Initiate``) for each state that requires updating on every node. + + * You can do this manually via RPC but for anything more than a couple of states it is assumed that a script will be + provided by the CorDapp developer to query the vault and run this for all states + * The contract upgrade initiate flow only needs to be run on one of the participants for each state. The flow will + automatically upgrade the state on all participants. diff --git a/docs/source/node-operations-upgrading.rst b/docs/source/node-operations-upgrading.rst index d7c38a5c4f..80eeac8385 100644 --- a/docs/source/node-operations-upgrading.rst +++ b/docs/source/node-operations-upgrading.rst @@ -1,5 +1,5 @@ -Node upgrades -============= +Upgrade a Corda Node to Corda Enterprise +======================================== Upgrading the version of Corda on a node ---------------------------------------- @@ -41,13 +41,17 @@ To upgrade a node running on Corda 3.x to Corda Enterprise 3.0: Database upgrades ~~~~~~~~~~~~~~~~~ -For running existing CorDapps built against Corda open source against Corda Enterprise 3.0, the following database changes -are required: +When upgrading an existing node from Corda 3.x to Corda Enterprise, the node operator has the option of using one of the enterprise +database engines that are supported (see :doc:`node-database`). +We highly recommend moving away from the default H2 database when setting up a production node. -* The ``net.corda.core.schemas.PersistentStateRef`` fields (``index`` and ``txId``) were incorrectly marked as nullable - in previous versions and are now non-nullable ( see :doc:`changelog` for more information). +Also, on Corda Enterprise we have integrated Liquibase to track database changes. See :doc:`database-management`, for more info. - * To upgrade using a H2 database: + +Migrating existing data from a Corda 3.0 or 3.1 H2 database to the Corda Enterprise database +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +I) Backup the database and run the following statements in order to align the database with Corda Enterprise: For CorDapps persisting custom entities with ``PersistentStateRef`` used as a non Primary Key column, the backing table needs to be updated. In SQL replace ``your_transaction_id``/``your_output_index`` column names with your custom names, if the entity doesn't use the JPA @@ -79,88 +83,25 @@ are required: and needs to be preserved, you would need to create a copy of the ``PersistentStateRef`` class with a different name and use the new class in your entity. - No action is needed for default node tables, or custom CorDapp entities using ``PersistentStateRef`` as a Primary Key, as + No action is needed for default node tables, or custom CorDapp entities using ``PersistentStateRef`` as a primary key, as in this case the backing columns are automatically not nullable. -* A table name with a typo has been corrected + * A table name with a typo has been corrected - * To upgrade using a H2 database: + .. sourcecode:: sql - While the node is stopped, run the following SQL statement for each database instance and schema: + ALTER TABLE [schema.]NODE_ATTCHMENTS_CONTRACTS RENAME TO NODE_ATTACHMENTS_CONTRACTS; - .. sourcecode:: sql + The ``schema`` parameter is optional. - ALTER TABLE [schema.]NODE_ATTCHMENTS_CONTRACTS RENAME TO NODE_ATTACHMENTS_CONTRACTS; + .. note:: Don't forget to backup the H2 database as after the changes the database will no longer be compatible with a Corda 3.0 or 3.1 node. - The ``schema`` parameter is optional. +II) Export the data from the H2 database using a specialized tool. -Upgrading the version of a CorDapp on a node -Upgrading CorDapps on a node ----------------------------- +III) Prepare a new database and import the data: -In order to upgrade a CorDapps on a node to a new version, it needs to be determined whether any backwards compatible -changes have been made. + - Use the database management tool (see :doc:`database-management`) to setup the database schema. + - Import the data into the new database. -For developer information on upgrading CorDapps, see :doc:`upgrading-cordapps`. -Flow upgrades -~~~~~~~~~~~~~ - -If any backwards-incompatible changes have been made (see :ref:`upgrading-cordapps-backwards-incompatible-flow-changes` -for more information), the upgrade method detailed below will need to be followed. Otherwise the CorDapp JAR can just -be replaced with the new version. - -Contract and State upgrades -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -There are two types of contract/state upgrade: - -1. *Implicit:* By allowing multiple implementations of the contract ahead of time, using constraints. See - :doc:`api-contract-constraints` to learn more. -2. *Explicit:* By creating a special *contract upgrade transaction* and getting all participants of a state to sign it using the - contract upgrade flows. - -This documentation only considers the *explicit* type of upgrade, as implicit contract upgrades are handled by the application. - -In an explicit upgrade contracts and states can be changed in arbitrary ways, if and only if all of the state's participants -agree to the proposed upgrade. The following combinations of upgrades are possible: - -* A contract is upgraded while the state definition remains the same. -* A state is upgraded while the contract stays the same. -* The state and the contract are updated simultaneously. - -Running the upgrade -~~~~~~~~~~~~~~~~~~~ - -If a contract or state requires an explicit upgrade then all states will need updating to the new contract at a time agreed -by all participants. The updated CorDapp JAR needs to be distributed to all relevant parties in advance of the changeover -time. - -In order to perform the upgrade, follow the following steps: - -* If required, do a flow drain to avoid the definition of states or contracts changing whilst a flow is in progress (see :ref:`upgrading-cordapps-flow-drains` for more information) - - * By RPC using the ``setFlowsDrainingModeEnabled`` method with the parameter ``true`` - * Via the shell by issuing the following command ``run setFlowsDrainingModeEnabled enabled: true`` - -* Check that all the flows have completed - - * By RPC using the ``stateMachinesSnapshot`` method and checking that there are no results - * Via the shell by issuing the following command ``run stateMachinesSnapshot`` - -* Once all flows have completed, stop the node -* Replace the existing JAR with the new one -* Make any database changes required to any custom vault tables for the upgraded CorDapp -* Restart the node -* If you drained the node prior to upgrading, switch off flow draining mode to allow the node to continue to receive requests - - * By RPC using the ``setFlowsDrainingModeEnabled`` method with the parameter ``false`` - * Via the shell by issuing the following command ``run setFlowsDrainingModeEnabled enabled: false`` - -* Run the contract upgrade authorisation flow (``ContractUpgradeFlow$Initiate``) for each state that requires updating on every node. - - * You can do this manually via RPC but for anything more than a couple of states it is assumed that a script will be - provided by the CorDapp developer to query the vault and run this for all states - * The contract upgrade initiate flow only needs to be run on one of the participants for each state. The flow will - automatically upgrade the state on all participants.