ExternalVendorCode/corda
1
0
Fork 0
mirror of https://github.com/corda/corda.git synced 2025-05-30 06:04:24 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

[ENT-1893]: Db evolution documentation for CorDapp developers. (#986)

Browse Source
This commit is contained in:
Michele Sollecito 2018-06-13 13:25:23 +01:00 committed by GitHub
parent bc93275f00
commit a4a75cf22d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 11 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
docs/source/database-management.rst
View File

@ -40,6 +40,11 @@ As a database migration framework, we use the open source library `Liquibase <ht
Once such a change has been applied to the actual database, this fact is recorded in the database by the database migration library (see below), Once such a change has been applied to the actual database, this fact is recorded in the database by the database migration library (see below),
hence providing a mechanism to determine the 'version' of any given schema. hence providing a mechanism to determine the 'version' of any given schema.
.. warning::
Contract state tables created by CorDapps must remain backwards compatible between releases.
This means that they can evolve only by adding columns to them, and not by repurposing or deleting existing ones.
The reason for this is that this part of the database schema constitutes part of the CorDapp API, and third-party systems can integrate at the database level with Corda.
If you need to break compatibility, you have the option of creating a new version of the ``MappedSchema`` with new tables, but you would then have to write to both the old and the new version.
About Liquibase About Liquibase
--------------- ---------------
@ -48,10 +53,10 @@ Liquibase is a tool that implements an automated, version based database migrati
large number of databases. It works by maintaining a list of applied changesets. A changeset can be something very large number of databases. It works by maintaining a list of applied changesets. A changeset can be something very
simple like adding a new column to a table. It stores each executed changeset with columns like id, author, timestamp, simple like adding a new column to a table. It stores each executed changeset with columns like id, author, timestamp,
description, md5 hash, etc in a table called ``DATABASECHANGELOG``. This changelog table will be read every time a description, md5 hash, etc in a table called ``DATABASECHANGELOG``. This changelog table will be read every time a
migration command is run to determine what changesets need to be executed. It represents the "version" of the database migration command is run to determine what change-sets need to be executed. It represents the "version" of the database
(the sum of the executed changesets at any point). Changesets are scripts written in a supported format (xml, yml, (the sum of the executed change-sets at any point). Change-sets are scripts written in a supported format (xml, yml,
sql), and should never be modified once they have been executed. Any necessary correction should be applied in a new sql), and should never be modified once they have been executed. Any necessary correction should be applied in a new
changeset. change-set.
For documentation around Liquibase see: `The Official website <http://www.liquibase.org>`_ and `Tutorial <https://www.thoughts-on-java.org/database-migration-with-liquibase-getting-started>`_. For documentation around Liquibase see: `The Official website <http://www.liquibase.org>`_ and `Tutorial <https://www.thoughts-on-java.org/database-migration-with-liquibase-getting-started>`_.
@ -75,9 +80,9 @@ Migration scripts structure
Corda provides migration scripts in an XML format for its internal node and vault tables. CorDapps should provide Corda provides migration scripts in an XML format for its internal node and vault tables. CorDapps should provide
migration scripts for the tables they manage. In Corda, ``MappedSchemas`` (see :doc:`api-persistence`) manage JPA migration scripts for the tables they manage. In Corda, ``MappedSchemas`` (see :doc:`api-persistence`) manage JPA
Entities and thus the corresponding database tables. So ``MappedSchemas`` are the natural place to point to the Entities and thus the corresponding database tables. So ``MappedSchemas`` are the natural place to point to the
changelog file(s) that contain the changesets for those tables. Nodes can configure which ``MappedSchemas`` are included changelog file(s) that contain the change-sets for those tables. Nodes can configure which ``MappedSchemas`` are included
which means only the required tables are created. To follow standard best practices, our convention for structuring the which means only the required tables are created. To follow standard best practices, our convention for structuring the
changelogs is to have a "master" changelog file per ``MappedSchema`` that will only include release changelogs (see example below). change-logs is to have a "master" changelog file per ``MappedSchema`` that will only include release change-logs (see example below).
Example: Example:
@ -267,7 +272,7 @@ production.
.. warning:: A very important aspect to be remembered is that the CorDapp will have to work on all supported Corda databases. .. warning:: A very important aspect to be remembered is that the CorDapp will have to work on all supported Corda databases.
It is the responsibility of the developers to test the migration scripts and the CorDapp against all the databases. It is the responsibility of the developers to test the migration scripts and the CorDapp against all the databases.
In the future we will provide aditional tooling to assist with this aspect. In the future we will provide additional tooling to assist with this aspect.
When developing a new version of an existing CorDapp, depending on the changes to the ``PersistentEntities``, a When developing a new version of an existing CorDapp, depending on the changes to the ``PersistentEntities``, a
changelog will have to be created as per the Liquibase documentation and the example above. changelog will have to be created as per the Liquibase documentation and the example above.