ExternalVendorCode/corda
1
0
Fork 0
mirror of https://github.com/corda/corda.git synced 2025-02-19 08:57:28 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

ENT-2180 Document clarifications (#1124)

Browse Source 
* ENT-2180 Document clarifications

* ENT-2180 Document clarifications

* ENT-2180 Address code review changes

* ENT-2180 Address code review changes
This commit is contained in:
Tudor Malene 2018-07-03 14:39:57 +01:00 committed by Michele Sollecito
parent a35ba7b59f
commit 911b5ec495
3 changed files with 93 additions and 80 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/source/corda-nodes-index.rst
View File

@ -14,4 +14,5 @@ Nodes
node-database node-database
node-administration node-administration
node-operations-upgrading node-operations-upgrading
node-operations-upgrade-cordapps
out-of-process-verification out-of-process-verification

71
docs/source/node-operations-upgrade-cordapps.rst Normal file
View File

@ -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.

101
docs/source/node-operations-upgrading.rst
View File

@ -1,5 +1,5 @@
Node upgrades Upgrade a Corda Node to Corda Enterprise
============= ========================================
Upgrading the version of Corda on a node 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 Database upgrades
~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~
For running existing CorDapps built against Corda open source against Corda Enterprise 3.0, the following database changes When upgrading an existing node from Corda 3.x to Corda Enterprise, the node operator has the option of using one of the enterprise
are required: 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 Also, on Corda Enterprise we have integrated Liquibase to track database changes. See :doc:`database-management`, for more info.
in previous versions and are now non-nullable ( see :doc:`changelog` for more information).
* 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. 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 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 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. 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. 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 - Use the database management tool (see :doc:`database-management`) to setup the database schema.
changes have been made. - 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.