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

ENT-1709 Documentation for standalone database setup (#949)

Browse Source 
Added SQL scripts to create database/clean up database, example CordFormation to use with remote database, several clarifications.
This commit is contained in:
szymonsztuka
2018-06-08 16:50:47 +01:00
committed by GitHub
parent 2fce979fe7
commit 68fcda5548
2 changed files with 281 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files

86
docs/source/testing.rst
View File

@ -43,26 +43,13 @@ TODO: Add instructions on manual testing
External Database Testing
-------------------------
Integration tests can be parameterised to run against any remote database (instead of the default embeded H2 instance).
Running a node against a remote database requires several setup steps including a database setup/cleanup and adding a JDBC driver JAR to the node.
All required steps are described in :ref:`Standalone database <standalone_database_config_examples_ref>`.
Integration Tests
~~~~~~~~~~~~~~~~~
Integration tests can be parameterised to run against any remote database (instead of the default embedded H2 instance).
When running Gradle task `integrationTest`, a combination of several system properties (passed as `-Dproperty=...`) can modify the node default JDBC setting and trigger a database setup before and after each test.
The property ``custom.databaseProvider`` is resolved at run-time to load a configuration file on the classpath with the
name `$custom.databaseProvider.conf` containing database configuration properties. These settings override the default H2 ones
defined in the node configuration file (see ``reference.conf``).
Integration test runs predefined set of SQL setup scripts selected for a specific database provider by ``test.db.script.dir``.
SQL scripts are templates which contain SQL DDL statements with the `${schema}` placeholder.
Integration tests run the script for all nodes involved in the test and replace `${schema}` with the appropriate value, derived from a node name. SQL templates files are executed at different stage of the integration test:
- ``db-global-setup.sql``- before a test class (@BeforeClass), should create database users, schema and permissions
- ``db-setup.sql`` - before a test (@Before), should clean up/drop tables
- ``db-cleanup.sql`` - after a test (@After), may clean up/drop tables
- ``db-global-cleanup.sql`` - after a test class (@AfterClass), may drop user and schema
Not all stages need to be present e.g. when ``db-setup.sql`` deletes all tables before a test then ``db-cleanup.sql`` after the test is not needed.
The setup ensures that all nodes involved in a single integration test use different database users to achieve database separation.
The configuration file (denoted by the ``custom.databaseProvider`` property) define a user and a schema as `${custom.nodeOrganizationName}` value.
The value is a placeholder which is resolved at runtime to a node organization name.
To run integration tests against a remote database provide these system properties:
@ -76,8 +63,7 @@ To run integration tests against a remote database provide these system properti
- ``corda.dataSourceProperties.dataSource.url`` - specify full JDBC connection string use by a node to connect to database, JDBC URL provided by the predefined configuration file (by ``databaseProvider``) doesn't contain specific host names and port
- ``corda.dataSourceProperties.dataSource.password`` - optional parameter, currently a database user password in the SQL setup script ``test.db.script.dir`` matches one in the node configuration file ``test.db.script.dir``
- ``corda.dataSourceProperties.dataSource.password`` - optional parameter, defaults to a password set in the SQL scripts from ``test.db.script.dir``
Example running Gradle integration tests task against Azure SQL database at `mycordadb.database.windows.net` host:
@ -89,5 +75,65 @@ Example running Gradle integration tests task against Azure SQL database at `myc
-Dtest.db.admin.password='paSSword(!' \
-Dtest.db.script.dir=database-scripts/sql-azure
Several Gradle task parameters and additional setup code enable running against custom databases.
The property ``custom.databaseProvider`` is resolved at runtime to load a configuration file on the classpath with the
name ``$custom.databaseProvider.conf`` containing database configuration properties. These settings override the default H2 ones
defined in the node configuration file (see ``reference.conf``).
Integration test run a predefined set of SQL setup scripts selected for a specific database provider by ``test.db.script.dir``.
Integration tests run the script for all nodes involved in the test and replace `${schema}` with the appropriate value, derived from a node name. SQL templates files are executed at different stage of the integration test:
- ``db-global-setup.sql``- before a test class (@BeforeClass), should create database users, schema and permissions
- ``db-setup.sql`` - before a test (@Before), should clean up/drop tables
- ``db-cleanup.sql`` - after a test (@After), may clean up/drop tables
- ``db-global-cleanup.sql`` - after a test class (@AfterClass), may drop user and schema
Not all stages need to be present e.g., when ``db-setup.sql`` deletes all tables before a test then ``db-cleanup.sql`` after the test is not needed.
The setup ensures that all nodes involved in a single integration test use different database users to achieve database separation.
The configuration file (denoted by the ``custom.databaseProvider`` property) defines a user and a schema based on the `${custom.nodeOrganizationName}` value.
The value is a placeholder which is resolved at runtime to a node organization name.
.. _testing_cordform_ref:
Cordform Gradle task
~~~~~~~~~~~~~~~~~~~~
Cordform task ``deployNodes`` can be modified to override default H2 database settings.
For each node element add `extraConfig`` with all JDBC/database properties as described in :ref:`Node configuration <standalone_database_config_examples_ref>`.
.. code:: bash
task deployNodes(type: net.corda.plugins.Cordform, dependsOn: ['jar']) {
...
node {
...
extraConfig = [
'dataSourceProperties.dataSource.url' : 'jdbc:sqlserver://[DATABASE].database.windows.net:1433;databaseName=[DATABASE];encrypt=true;trustServerCertificate=false;hostNameInCertificate=*.database.windows.net;loginTimeout=30',
'dataSourceProperties.dataSourceClassName' : 'com.microsoft.sqlserver.jdbc.SQLServerDataSource',
'dataSourceProperties.dataSource.user' : '[USER]',
'dataSourceProperties.dataSource.password' : '[PASSWORD]',
'jarDirs' : ['path_to_jdbc_driver_dir'],
'database.transactionIsolationLevel' : 'READ_COMMITTED',
'database.schema' : '[SCHEMA]',
'database.runMigration' : 'true'
]
The Cordform task doesn't create/cleanup the database and doesn't download the required JDBC driver JAR.
Manual database setup is described in :ref:`Node configuration <standalone_database_config_examples_ref>`.
.. note::
The Cordform task can be used to deploy nodes distributed with Capsule only, as currently the task doesn't copy JDBC driver JAR files to the ``./drivers`` subdirectory and uses paths from the ``jarDirs`` property instead.
DriverDSL
~~~~~~~~~
A node started programmatically via the ``DriverDSL`` can be configured to use a remote database.
The JDBC driver JAR needs to be added as a Gradle runtime dependency for the ``node`` module in ``build.gradle``.
The file already contains conditional addition of JDBC dependencies of supported databases.
For a given JDBC dependency, copy it outside of the conditional to ensure that it is always gets added to the node JAR.
For each node, pass JDBC/database properties described in :ref:`Node configuration <standalone_database_config_examples_ref>` via the ``customOverrides`` parameter of the ``startNode`` method, e.g.:
.. code:: kotlin
startNode(providedName = ALICE_NAME, rpcUsers = listOf(demoUser), customOverrides = aliceDatabaseProperties)
``DriverDSL`` doesn't create/cleanup database. Manual database setup is described in :ref:`Node configuration <standalone_database_config_examples_ref>`.