From 7b3ab9bd24d9be11e6068c494fea0a642a8cd7c3 Mon Sep 17 00:00:00 2001 From: Arnold Galovics Date: Wed, 16 Mar 2022 13:06:13 +0100 Subject: [PATCH] FINERACT-849: Minor fixes + docs for EclipseLink/PostgreSQL support --- build.gradle | 6 +- fineract-doc/.asciidoctorconfig | 2 +- fineract-doc/build.gradle | 5 +- fineract-doc/src/docs/en/02_architecture.adoc | 66 ++++++++++++++++++- fineract-doc/src/docs/en/colophon.adoc | 2 + fineract-doc/src/docs/en/config.adoc | 2 +- 6 files changed, 72 insertions(+), 11 deletions(-) diff --git a/build.gradle b/build.gradle index bfcbc3a1d..b8ca8f9be 100644 --- a/build.gradle +++ b/build.gradle @@ -45,9 +45,9 @@ buildscript { dependencies { classpath 'com.bmuschko:gradle-cargo-plugin:2.9.0' - classpath 'org.eclipse.persistence:eclipselink:3.0.2' - classpath 'jakarta.ws.rs:jakarta.ws.rs-api:3.0.0' - classpath('com.google.cloud.tools:jib-layer-filter-extension-gradle:0.1.0') + classpath 'org.eclipse.persistence:eclipselink:2.7.10' + classpath 'jakarta.ws.rs:jakarta.ws.rs-api:2.1.6' + classpath 'com.google.cloud.tools:jib-layer-filter-extension-gradle:0.1.0' } } diff --git a/fineract-doc/.asciidoctorconfig b/fineract-doc/.asciidoctorconfig index 5ccca4a65..5b1ed1d8f 100644 --- a/fineract-doc/.asciidoctorconfig +++ b/fineract-doc/.asciidoctorconfig @@ -1,4 +1,4 @@ -:years: 2015-2020 +:years: 2015-2022 :revnumber: 1.0.0 :draft: true :rootdir: ../../../.. diff --git a/fineract-doc/build.gradle b/fineract-doc/build.gradle index e216001da..b457ada2e 100644 --- a/fineract-doc/build.gradle +++ b/fineract-doc/build.gradle @@ -44,13 +44,10 @@ asciidoctorj { version = '2.4.0' attributes = [ - revnumber: { - project.version.toString() - }, generated: "${buildDir}/generated/asciidoc", imagesdir: 'images', diagrams: 'diagrams', - years: '2015-2020', + years: '2015-2022', revnumber: "$version".toString(), rootdir: "$rootDir".toString(), baseurl: 'fineract.apache.org' diff --git a/fineract-doc/src/docs/en/02_architecture.adoc b/fineract-doc/src/docs/en/02_architecture.adoc index 6bb82bcfa..3fc1afad7 100644 --- a/fineract-doc/src/docs/en/02_architecture.adoc +++ b/fineract-doc/src/docs/en/02_architecture.adoc @@ -99,10 +99,11 @@ At a higher level though we see the capabilities fall into the following categor ** Spring Framework ** Spring Boot ** Spring Security -** Spring Data (JPA) backed by Hibernate +** Spring Data (JPA) backed by EclipseLink * MySQL: http://www.oracle.com/us/products/mysql/overview/index.html +* PostgreSQL -=== Principals +=== Principles ==== RESTful API @@ -208,3 +209,64 @@ NOTE: if a RollbackTransactionAsCommandIsNotApprovedByCheckerException occurs at * Process command using handler (In transactional scope). * CommandSource object created/updated with all details for logging to 'm_portfolio_command_source' table. * In update scenario, we check to see if there where really any changes/updates. If so only JSON for changes is stored in audit log. + +=== Database support + +Fineract supports multiple databases: + +* MySQL compatible databases (e.g. MariaDB) +* PostgreSQL + +The platform differentiates between these database types in certain cases when there's a need to use some database specific tooling. To do so, the platform examines the JDBC driver used for running the platform and tries to determine which database is being used. + +The currently supported JDBC driver and corresponding mappings can be found below. + +[cols="1,1"] +|=== +|*JDBC driver class name* +|*Resolved database type* + +|`org.mariadb.jdbc.Driver` +|MySQL + +|`com.mysql.jdbc.Driver` +|MySQL + +|`org.postgresql.Driver` +|PostgreSQL + +|=== + +The actual code can be found in the `DatabaseTypeResolver` class. + +=== Data-access layer + +The data-access layer of Fineract is implemented by using JPA (Java Persistence API) with the EclipseLink provider. +Despite the fact that JPA is used quite extensively in the system, there are cases where the performance is a key element for an operation therefore you can easily find native SQLs as well. + +The data-access layer of Fineract is compatible with different databases. Since a lot of the native queries are using specific database functions, a wrapper class - `DatabaseSpecificSQLGenerator` - has been introduced to handle these database specifics. Whenever there's a need to rely on new database level functions, make sure to extend this class and implement the specific functions provided by the database. + +Fineract has been developed for 10+ years by the community and unfortunately there are places where entity relationships are configured with `EAGER` fetching strategy. This must not confuse anybody. The long-term goal is to use the `LAZY` fetching strategy for every single relationship. If you're about to introduce a new one, make sure to use `LAZY` as a fetching strategy, otherwise your PR will be rejected. + +=== Database schema migration + +As for every system, the database structure will and need to evolve over time. Fineract is no different. Originally for Fineract, Flyway was used until Fineract 1.6.x. + +After 1.6.x, PostgreSQL support was added to the platform hence there was a need to make the data-access layer and the schema migration as database independent as possible. Becuase of that, from Fineract 1.7.0, Flyway is not used anymore but Liquibase is. + +Some of the changesets in the Liquibase changelogs have database specifics into it but they only run for the relevant databases. This is controller by Liquibase contexts. + +The currently available Liquibase contexts are: + +* `mysql` - only set when the database is a MySQL compatible database (e.g. MariaDB) +* `postgresql` - only set when the database is a PostgreSQL database +* configured Spring active profiles +* `tenant_store_db` - only set when the database migration runs the Tenant Store upgrade +* `tenant_db` - only set when the database migration runs the Tenant upgrade +* `initial_switch` - this is a technical context and should *NOT* be used + +The switch from Flyway (1.6.x) to Liquibase (1.7.x) was planned to be as smooth as possible so there's no need for manual work hence the behavior is described as following: + +* If the database is empty, Liquibase will create the database schema from scratch +* If the database contains the latest Fineract 1.6.x database structure which was previously migrated with Flyway. Liquibase will seamlessly upgrade it to the latest version. Note: the Flyway related 2 database tables are left as they are and are not deleted. +* If the database contains an earlier version of the database structure than Fineract 1.6.x. Liquibase will *NOT* do anything and *will fail the application during startup*. The proper approach in this case is to first upgrade your application version to the latest Fineract 1.6.x so that the latest Flyway changes are executed and then upgrade to the newer Fineract version where Liquibase will seamlessly take over the database upgrades. \ No newline at end of file diff --git a/fineract-doc/src/docs/en/colophon.adoc b/fineract-doc/src/docs/en/colophon.adoc index fc073850b..70910c4bc 100644 --- a/fineract-doc/src/docs/en/colophon.adoc +++ b/fineract-doc/src/docs/en/colophon.adoc @@ -18,6 +18,7 @@ | Michael Vorburger | mailto:mike@vorburger.ch[] | Aleksandar Vidakovic | mailto:aleks@apache.org[] +| Arnold Galovics | mailto:arnold@apache.org[] |=== //ifdef::backend-pdf[] @@ -30,6 +31,7 @@ ^| Authors ^| Description ^| Date ^| Version | Aleksandar Vidakovic | Initial version | 2020-10-26 | 1.4.0 +| Arnold Galovics | Database architecture section | 2022-03-11 | 1.7.0 |=== toc::[] diff --git a/fineract-doc/src/docs/en/config.adoc b/fineract-doc/src/docs/en/config.adoc index 6727eabf2..897103e38 100644 --- a/fineract-doc/src/docs/en/config.adoc +++ b/fineract-doc/src/docs/en/config.adoc @@ -15,7 +15,7 @@ :source-language: java :diagramsdir: diagrams :imagesdir: images -:years: 2017-2020 +:years: 2017-2022 :lang: en :encoding: utf-8 :linkattrs: