mirror of
https://github.com/corda/corda.git
synced 2025-02-15 23:22:54 +00:00
ENT-2180 Document clarifications (#1124)
* 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
Michele Sollecito
parent
a35ba7b59f
commit
911b5ec495
@ -14,4 +14,5 @@ Nodes
|
||||
node-database
|
||||
node-administration
|
||||
node-operations-upgrading
|
||||
node-operations-upgrade-cordapps
|
||||
out-of-process-verification
|
||||
71
docs/source/node-operations-upgrade-cordapps.rst
Normal file
71
docs/source/node-operations-upgrade-cordapps.rst
Normal 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.
|
||||
@ -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.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user