From 437a05303771ccd22bab68f5b8e42f83efcfc0aa Mon Sep 17 00:00:00 2001 From: szymonsztuka Date: Wed, 31 Oct 2018 14:39:22 +0000 Subject: [PATCH] Minor docs update - Persistence API and node database (#4061) Note about database considerations regarding Cordapp compatibility between OS and ENT. Remove database configuration "schema" as this is not implemented in OS, it was already mentioned as ignored for SQL server. --- docs/source/api-persistence.rst | 7 ++++++- docs/source/node-database.rst | 14 ++++---------- 2 files changed, 10 insertions(+), 11 deletions(-) diff --git a/docs/source/api-persistence.rst b/docs/source/api-persistence.rst index 8fabd37e17..ef0b1ead76 100644 --- a/docs/source/api-persistence.rst +++ b/docs/source/api-persistence.rst @@ -100,7 +100,7 @@ associate a ``StateRef`` with a persisted representation of a ``ContractState`` unconsumed states in the vault. The ``PersistentState`` subclass should be marked up as a JPA 2.1 *Entity* with a defined table name and having -properties (in Kotlin, getters/setters in Java) annotated to map to the appropriate columns and SQL types. Additional +properties (in Kotlin, getters/setters in Java) annotated to map to the appropriate columns and SQL types. Additional entities can be included to model these properties where they are more complex, for example collections, so the mapping does not have to be *flat*. The ``MappedSchema`` must provide a list of all of the JPA entity classes for that schema in order to initialise the ORM layer. @@ -111,6 +111,11 @@ Several examples of entities and mappings are provided in the codebase, includin .. literalinclude:: ../../finance/src/main/kotlin/net/corda/finance/schemas/CashSchemaV1.kt :language: kotlin +.. note:: If Cordapp needs to be portable between Corda OS (running against H2) and Corda Enterprise (running against a standalone database), + consider database vendors specific requirements. + Ensure that table and column names are compatible with the naming convention of the database vendors for which the Cordapp will be deployed, + e.g. for Oracle database, prior to version 12.2 the maximum length of table/column name is 30 bytes (the exact number of characters depends on the database encoding). + Identity mapping ---------------- Schema entity attributes defined by identity types (``AbstractParty``, ``Party``, ``AnonymousParty``) are automatically diff --git a/docs/source/node-database.rst b/docs/source/node-database.rst index f9c7e3a06c..e40c3bf520 100644 --- a/docs/source/node-database.rst +++ b/docs/source/node-database.rst @@ -22,21 +22,17 @@ configuration for PostgreSQL: dataSourceProperties = { dataSourceClassName = "org.postgresql.ds.PGSimpleDataSource" - dataSource.url = "jdbc:postgresql://[HOST]:[PORT]/postgres" + dataSource.url = "jdbc:postgresql://[HOST]:[PORT]/[DATABASE]" dataSource.user = [USER] dataSource.password = [PASSWORD] } database = { transactionIsolationLevel = READ_COMMITTED - schema = [SCHEMA] } Note that: - -* The ``database.schema`` property is optional -* The value of ``database.schema`` is not wrapped in double quotes and Postgres always treats it as a lower-case value - (e.g. ``AliceCorp`` becomes ``alicecorp``) -* If you provide a custom ``database.schema``, its value must either match the ``dataSource.user`` value to end up +* Database schema name can be set in JDBC URL string e.g. currentSchema=myschema +* Database schema name must either match the ``dataSource.user`` value to end up on the standard schema search path according to the `PostgreSQL documentation `_, or the schema search path must be set explicitly for the user. @@ -56,15 +52,13 @@ an example node configuration for SQLServer: } database = { transactionIsolationLevel = READ_COMMITTED - schema = [SCHEMA] } jarDirs = ["[FULL_PATH]/sqljdbc_6.2/enu/"] Note that: -* The ``database.schema`` property is optional and is ignored as of release 3.1. * Ensure the directory referenced by jarDirs contains only one JDBC driver JAR file; by the default, - sqljdbc_6.2/enu/contains two JDBC JAR file for different Java versions. + sqljdbc_6.2/enu/contains two JDBC JAR files for different Java versions. Node database tables ^^^^^^^^^^^^^^^^^^^^