fineract-database
Add or change Apache Fineract database schema and seed data with Liquibase, covering where a changelog part goes and how it is included, the PostgreSQL and MySQL contexts, the DDL safety, registration and backward-compatibility checks, seed rows such as permissions and configurations, and how Java code reaches the database. Use when adding or editing a Liquibase changelog, a table, column, index or seed row, a JPA relationship or a native SQL query, or when a database check fails in CI.
- License 许可
- Apache-2.0
- 所属仓库
- apache/fineract
- 最近更新
- 2026-11-15
- Stars
- ★ 2.6k
- Forks
- 3.0k
01 前言 Front Matter
- name
- fineract-database
- description
- Add or change Apache Fineract database schema and seed data with Liquibase, covering where a changelog part goes and how it is included, the PostgreSQL and MySQL contexts, the DDL safety, registration and backward-compatibility checks, seed rows such as permissions and configurations, and how Java code reaches the database. Use when adding or editing a Liquibase changelog, a table, column, index or seed row, a JPA relationship or a native SQL query, or when a database check fails in CI.
03 SKILL.md 正文
Fineract Database Changes
Paths are relative to the repository root, db.changelog-master.xml is
fineract-provider/src/main/resources/db/changelog/db.changelog-master.xml, and
persistence.adoc is fineract-doc/src/docs/en/chapters/architecture/persistence.adoc. Each
rule below comes from the file or check named next to it; if this skill and that source
disagree, the source wins.
Where a change goes
Liquibase runs only the changelogs that db.changelog-master.xml reaches. Each tree has
its own parts directory, its own numbering and its own master changelog:
| Tables of | Parts directory | Included by |
|---|---|---|
| The tenant database (core) | fineract-provider/src/main/resources/db/changelog/tenant/parts |
tenant/changelog-tenant.xml |
The tenant store (fineract_tenants) |
fineract-provider/src/main/resources/db/changelog/tenant-store/parts |
tenant-store/changelog-tenant-store.xml |
| A module with its own tree (loan, savings, progressive loan, working capital loan, loan origination, investor, command) | <module>/src/main/resources/db/changelog/tenant/module/<name>/.../parts |
The module-changelog-master.xml that includes the other parts of that directory |
- Put the change in the tree of the module that owns the table. A core part that alters a
module's tables goes in
tenant/final-changelog-tenant.xml, which runs after the modules (comment indb.changelog-master.xml). - Name the file with the next free number of that directory and what it does, like
0248_add_dates_to_client_identifier.xmlin the core tree, and add its<include>at the end of the master changelog. Another open PR may take the same number first; renumber when you rebase. - Run
./scripts/check-liquibase-changelog-registration.sh --base-ref origin/develop. It fails on a part that no master includes, a master thatdb.changelog-master.xmldoes not reach, a file included twice or an include of a missing file, and warns when a new part reuses a number. CI runs it in.github/workflows/verify-liquibase-changelog-registration.yml. Run it again after resolving a conflict in a master changelog: a lost<include>breaks nothing visibly, the part just never runs. - Never edit, rename or move a changeset that is already on develop; add a new one.
Liquibase identifies a changeset by its id, author and file path, so a moved file runs
again, and it refuses to start when the checksum of a changeset it has run changes. The
few old changesets that were edited carry
<validCheckSum>entries, for examplefineract-provider/src/main/resources/db/changelog/tenant/parts/0015_add_business_date.xml.
Databases and contexts
- PostgreSQL is the supported database; MySQL and MariaDB are deprecated but still
supported (
persistence.adoc, "Database support"). CI runs the integration tests on all three (.github/workflows/build-postgresql.ymland its MySQL and MariaDB variants). - The contexts are
mysql,postgresql,tenant_db,tenant_store_dband the active Spring profiles. Never useinitial_switch(persistence.adoc, "Database schema migration"). The includes indb.changelog-master.xmlalready settenant_dbortenant_store_db, so a part only needscontext="mysql"orcontext="postgresql"on the changesets whose types or SQL differ. - Where the types differ, write one changeset per database. For example,
fineract-loan-origination/src/main/resources/db/changelog/tenant/module/loanorigination/parts/0005_wc_loan_originator_mapping.xmldeclarescreated_on_utcasDATETIME(6)on MySQL andTIMESTAMP WITH TIME ZONEon PostgreSQL, withcreated_byandlast_modified_byas foreign keys tom_appuser. - For the current date, the current time or a UUID in a changeset, use the
${current_date},${current_datetime}and${uuid}properties defined at the top ofdb.changelog-master.xml. - In Java, put a database-specific function in a native query through
DatabaseSpecificSQLGenerator, and extend it when a function is missing (persistence.adoc, "Data-access layer"). - Map every new JPA relationship with
FetchType.LAZY; a PR that adds anEAGERone is rejected (persistence.adoc, "Data-access layer").
DDL safety
.github/workflows/verify-liquibase-ddl-safety.yml runs scripts/check-liquibase-ddl-safety.sh
on the changelog files a PR changes. Run it locally with
./scripts/check-liquibase-ddl-safety.sh --base-ref origin/develop --head-ref HEAD.
- On MySQL, declare date-time columns as
DATETIME(6). A plainDATETIMEblocks the build, because MySQL would drop the fractional seconds. On PostgreSQL, the_utcand audit columns areTIMESTAMP WITH TIME ZONE, so write one changeset per database for them (point 3 of "Databases and contexts"). - An index on a table that the PR does not create must not lock it on PostgreSQL. Use raw
CREATE INDEX CONCURRENTLYin a changeset withrunInTransaction="false"andcontext="postgresql", and a separate MySQL changeset, asfineract-provider/src/main/resources/db/changelog/tenant/parts/0177_acc_journal_entry_index.xmldoes. A<createIndex>on such a table blocks the build unless its changeset runs only on MySQL. dropColumn,dropTable,renameColumn,renameTable,modifyDataType,addNotNullConstraint, and anaddColumnwithnullable="false"and no default block the build on the tables listed inconfig/liquibase/critical-tables.txt, and are warnings on other tables.config/liquibase/dangerous-operations.txtgives the reason for each. The check treats tables that the same PR creates as safe.- The
ddl-safety-overridelabel makes the check report without blocking. Only a maintainer can add it, so explain in the PR why the operation is safe.
Backward compatibility
During a rolling upgrade the old code runs against the new schema, so add columns as
nullable or with a default, and drop or rename a column only after a release in which no
code uses it (config/liquibase/dangerous-operations.txt). These workflows, called from
.github/workflows/full-build-ci.yml, check the migrations:
verify-liquibase-backward-compatibility.ymlstarts the base commit's backend on a fresh PostgreSQL database, then starts the PR's backend on the same database, so every new changeset must run as an upgrade.regression-safety-db-changes.ymlruns on PRs that change a changelog. It runs the@RegressionSafetyE2E scenarios three times: old code with the old schema, old code with the new schema, and new code with the new schema. A failure only in the second run means the old code cannot work with the new schema.liquibase-only-postgresql.ymlruns the migrations alone, with theliquibase-onlySpring profile, on a fresh PostgreSQL database.
Seed rows
Some changes need a row that the code expects to exist. Insert it in the same change:
| When you add | Insert a row into | Example |
|---|---|---|
| A command or another action that checks a permission | m_permission, and for a write command also its <CODE>_CHECKER row |
fineract-working-capital-loan/src/main/resources/db/changelog/tenant/module/workingcapitalloan/parts/0084_wc_loan_missing_command_permissions.xml |
| A global configuration | c_configuration |
fineract-provider/src/main/resources/db/changelog/tenant/parts/0267_add_retained_earning_wc_report_global_configuration.xml |
A scheduler job (JobName value) |
job |
fineract-savings/src/main/resources/db/changelog/tenant/module/savings/parts/parts/2001_add_savings_accrual_job.xml |
| An external business event type | m_external_event_configuration, with enabled false |
fineract-provider/src/main/resources/db/changelog/tenant/parts/0243_add_client_lifecycle_event_configuration.xml |
- Tests that run as the superuser do not notice a missing
m_permissionrow. It fails only when maker-checker is enabled, whereConfigurationDomainServiceJpa.isMakerCheckerEnabledForTaskthrowsPermissionNotFoundException, or for a role that needs to be granted the permission. Without the<CODE>_CHECKERrow (action_name<ACTION>_CHECKER), onlyCHECKER_SUPER_USERcan approve the command, becausePortfolioCommandSourceWritePlatformServiceImplcheckstaskPermission + "_CHECKER". The 0084 example adds such rows that were missing. - Guard an insert with
<preConditions onFail="MARK_RAN">and asqlCheckfor the row, as them_permissionandc_configurationexamples above do, so that a database that already has the row skips the changeset. - Integration tests compare some of these tables with lists kept by hand:
GlobalConfigurationHelper,SchedulerJobsTestandExternalEventConfigurationTestDatainintegration-tests. Update them in the same change.
Verify
- Run the registration and DDL safety scripts above.
- Start the backend on a fresh database (
CONTRIBUTING.md, "Cucumber E2E tests", showscreatePGDBandbootRun) and read the log for the changesets that ran. Then start it on a database that develop created, to check the upgrade. - If you wrote a changeset for one database only, check the other one too, or watch the MySQL and MariaDB jobs in CI: the PostgreSQL run cannot catch it.