From d6235cb937cff5ada4716366bf5407dee066d708 Mon Sep 17 00:00:00 2001 From: Tudor Malene Date: Thu, 11 Jan 2018 15:41:46 +0000 Subject: [PATCH] [ENT-1364]: add documentation around liquibase and CorDapps (#322) (#341) * [ENT-1364]: add documentation around liquibase and CorDapps * [ENT-1364]: add documentation around liquibase and CorDapps * [ENT-1364]: add documentation around liquibase and CorDapps * [ENT-1364]: formatting * [ENT-1364]: formatting * [ENT-1364]: formatting * PR changes * [ENT-1364]: added more clarifications --- docs/source/api-persistence.rst | 56 ++++++++++++++++++++++++++------- 1 file changed, 44 insertions(+), 12 deletions(-) diff --git a/docs/source/api-persistence.rst b/docs/source/api-persistence.rst index ee3b0352c7..109f9c7dc4 100644 --- a/docs/source/api-persistence.rst +++ b/docs/source/api-persistence.rst @@ -18,10 +18,11 @@ The ORM mapping is specified using the `Java Persistence API . -If migration is enabled, the database state is checked (and updated) during node startup. (After deploying a new version of the code that contains database migrations, they are executed at that point). -Possible database changes range from schema changes to data changes. -If migration is disabled (the default), then on node startup, the database "version" is checked if it is up-to-date with the deployed code. +If migration is enabled (using the `database.runMigration` node configuration), the database state is checked (and updated) during node startup. +For example, after deploying a new version of the code that contains database migrations (see example below for a possible scenario), they are executed at that point (during startup). +Possible database changes range from schema changes to data changes (organized on changesets) -Liquibase will create a table called ``DATABASECHANGELOG``, that will store useful information about each change ( like timestamp, description, user, md5 hash so it can't be changed, etc) +Liquibase will create a table called ``DATABASECHANGELOG``, that will store information about each executed change (like timestamp, description, user, md5 hash so it can't be changed, etc). +This table will be used every time a migration is run to determine what changesets need to be applied. +Changesets should never be modified once they were executed. Any correction should be applied in a new changeset. We can also "tag" the database at each release to make rollback easier. Database changes are maintained in several xml files per ``MappedSchema``, so that only migrations corresponding to the node’s configured schemas are run. -For example, on the node-info schema, if there are any database changes for release 12, the changes will be added to a new file called: ``node-info.changelog-v12.xml`` which has to be included in ``node-info.changelog-master.xml``. +By following our convention, and using the node-info schema as an example, if there are any database changes for release 12, the changes will be added to a new file called: ``node-info.changelog-v12.xml`` which has to be included in ``node-info.changelog-master.xml``. Example: @@ -188,7 +191,7 @@ The ``DBAttachment`` entity is included in the ``NodeServicesV1`` schema, so we .. code-block:: xml - + @@ -233,6 +236,35 @@ Configurations: Command line arguments: -- To export the migration to a file use `—just-generate-database-migration outputSqlFile`. This will generate the delta from the last release, and will output the resulting sql into the outputSqlFile. It will not write to the db. It will not start the node! ( default value for `outputSqlFile` is a `.sql` file with the current date ) +- To export the migration to a file use `—just-generate-db-migration outputSqlFile`. This will generate the delta from the last release, and will output the resulting sql into the outputSqlFile. It will not write to the db. It will not start the node! ( default value for `outputSqlFile` is a `.sql` file with the current date) - To run the migration without starting the node: `--just-run-db-migration` + + +CorDapps: +--------- + +CorDapp developers who decide to store contract state in custom entities can create migration files for the ``MappedSchema`` they define. + +There are 2 ways of associating a migration file with a schema: + 1) By overriding ``val migrationResource: String`` and pointing to a file that needs to be in the classpath + 2) By putting a file on the classpath in a `migration` package whose name is the hyphenated name of the schema. ( All supported file extensions will be appended to the name) + +CorDapp developers can use any of the supported formats (xml, sql, json, yaml) for the migration files they create. + +In case CorDapp developers distribute their CorDapps with migration files, these will be automatically applied when the CorDapp is deployed on an R3 Corda node. +If they are deployed on a standard ("Open source") Corda node, then the migration will be ignored, and the database tables will be generated by Hibernate. + +In case CorDapp developers don't distribute a CorDapp with migration files, then the organisation that decides to deploy this CordApp on an R3 Corda ("Enterprise Blockchain") node has the responsibility to manage the database. + +The following options are available: + 1) In case the organisation is running a demo or trial node on the default H2 database, then the CorDapp will just work when deployed by relying on the migration tool provided by hibernate, which is not intended for production. + 2) In case the organisation is running a production node with live data on an enterprise database, then they will have to manage the database migration for the CorDapp. + + These are the steps to do this: + - find out the name of the MappedSchema containing the new contract state entities and hyphenate it. For example: + - `CommercialPaperSchemaV1` -> `commercial-paper-schema-v1.changelog-master.xml`. + - `IOUSchemaV1` -> `i-o-u-schema-v1.changelog-master.xml`. + - create a file with the preferred extension and add the migration in it (see ). For DBAs, the Sql format might be very familiar (basically T-SQL with metadata). The first changeset should be just creating the tables, indexes, etc. The author name should not be `R3.Corda`, because this is reserved. + - add the files to a folder named `migration` and create a jar (by convention it could be named: originalCorDappName-migration.jar), and deploy this jar together with the CorDapp + - by using the `--just-generate-db-migration` flag, the migration can be tested by inspecting the generated sql. \ No newline at end of file