Why a Fineract 1.6 to 1.7 upgrade is mainly a schema migration change and what the supported path requires
The key change in moving a self-hosted Fineract tenant from 1.6.x to 1.7 is the switch of schema migrations from Flyway to Liquibase. Databases older than 1.6 must first reach the latest 1.6.x, because Liquibase upgrades a database that already has the latest 1.6.x structure but fails at startup on older structures. Application code changes matter, but the schema path is what decides whether the upgrade starts cleanly.
Before planning the window, confirm three things in your own environment: the exact 1.6.x patch level of the tenant databases, the Fineract version each tenant runs, and whether any tenant was created or patched by hand outside the Flyway history. Check each tenant database separately, since a shared platform can hold tenants at different structure levels. If any tenant is below the latest 1.6.x, the supported path is to step that database up within the 1.6 line first, then move to 1.7 as a second, separate change with its own rollback point.
The behavior described here comes from the Fineract platform documentation at the Apache Fineract documentation, which is the source to check against your target release notes. Treat it as the reference for the switch itself, and record in your change plan which documentation version you followed. Where your deployment differs from the documented setup, such as custom migration scripts or a non-standard startup sequence, raise it with the project or your implementation partner before the cutover date is fixed.
What changes in Fineract 1.7 and what each change means for the upgrade
This table compares the migration tool before and after Fineract 1.7, the behavior of Liquibase on different schema states, and the cleanup left behind. Read each row as a question to answer about your database before you start the upgrade. The main takeaway is that the schema must already sit at the latest 1.6.x structure before Liquibase takes over.
| Change | What it means for the upgrade | Action needed |
|---|---|---|
| Migration tool before 1.7 | Fineract used Flyway for schema migrations up to and including the 1.6.x line. | Record the Fineract version your database last ran on and confirm it is 1.6.x or earlier. |
| Migration tool from 1.7.0 | Liquibase manages schema migrations from Fineract 1.7.0 onward. | Read the 1.7.0 release notes for any other schema or configuration changes beyond the tool switch. |
| Database already at latest 1.6.x structure | Liquibase upgrades this schema seamlessly. | Confirm the schema matches the latest 1.6.x structure before starting the 1.7 upgrade. |
| Database on an older structure | Liquibase fails at startup on structures older than the latest 1.6.x. | Upgrade to the latest 1.6.x first, then move to 1.7.0. Test this path on a copy of production. |
| Flyway tables after the switch | The two Flyway tables stay in the database and are not deleted by the upgrade. | Document them, leave them in place unless your change process approves removal, and exclude them from schema drift checks. |
| Failure at startup | An older structure surfaces as a startup failure, not a silent data change. | Keep a tested rollback point and review startup logs before routing traffic to the new version. |
How Liquibase takes over a Flyway-managed Fineract schema
When a Fineract 1.7 or later instance starts against a database that Flyway managed under 1.6.x, Liquibase reads its own changelog state and applies only the changes it has not yet recorded. The schema created by Flyway at the latest 1.6.x structure is the baseline Liquibase expects, so the upgrade proceeds without rebuilding tables. Your job before the first start is to confirm that the database is at that latest 1.6.x structure and that the backup you will restore from is a known-good copy. Liquibase changelogs run against the tenant databases your deployment is configured to migrate, so review which databases your tenants table lists before you start the first write instance.
If the schema is older than the latest 1.6.x structure, the Liquibase changesets assume tables, columns and constraints that do not exist yet. The application then fails at startup, and the failure appears in the instance logs rather than as a clean pre-check. This is why the project requires the stepwise path: run the latest 1.6.x release first, let it bring the schema up to date, and only then move to 1.7.0. Confirm the exact 1.6.x patch level in your environment with the Fineract documentation before you plan the sequence, since the supplied facts do not name a specific patch number.
The two Flyway tables are left in place after the switch. Fineract does not delete them, so they remain in your database as a record of the migration history that Flyway applied before 1.7. Treat them as inventory and audit evidence: a database scan, schema comparison or backup review will show them, and an auditor may ask why they exist. They are not an active control, and nothing in the 1.7 runtime reads them to decide what to apply, but that is a conclusion you should confirm in your own environment rather than assume. Do not drop them as cleanup. Document their presence in your upgrade record and keep them until your change process has signed off on the upgrade and the retention position is agreed.
What to prepare before touching the Fineract schema
The schema switch from Flyway to Liquibase is hard to reverse once it runs against a production tenant. The four preparation steps below establish what you are starting from, how you would recover, what else depends on the schema, and where you can rehearse the change safely.
Confirm the exact 1.6.x patch level
Record the precise 1.6.x release the instance runs, not just the minor line, and check the database structure against it before any change. Fineract's Liquibase switch in 1.7 upgrades a database at the latest 1.6.x structure, but fails at startup on older structures. If your schema is behind the latest 1.6.x, you must first step it up to that patch level, so this check decides whether you run one upgrade or two. Confirm the version on every tenant database, since tenants can drift apart.
Take a full backup and prove restore
Take a complete backup of every tenant database and the tenants database, then restore it to a separate server and start Fineract against the copy. A backup that has never been restored is an assumption, not a rollback plan. Record how long the restore took, because that is the minimum downtime you can count on if the migration must be reversed. Keep the backup until the upgraded system has passed your acceptance tests.
Inventory custom code touching the schema
List every custom module, plugin, SQL script, report and scheduled job that reads or writes Fineract tables directly, not only through the REST API. Direct table access breaks when Liquibase changes column names, indexes or constraints. Check each item against the target 1.7 structure and mark which ones need changes before the upgrade window opens. Pay attention to scripts run by a DBA or reporting tool outside your deployment pipeline.
Build a staging copy of production
Create a staging environment with the same Fineract version, the same tenant layout, a recent copy of production data and the same database platform. PostgreSQL is the recommended database for Fineract, so a staging database on a different engine tests a different migration. Run the Flyway-to-Liquibase switch there first and time it. Staging results only carry weight if the data volume and tenant count match production.
How to run the 1.6 to 1.7 upgrade in order, with checks and rollback points
This sequence moves a Fineract database from a verified 1.6.x structure to Liquibase-managed 1.7 with a checked backup and a defined rollback point at each stage. Each step closes with a check that tells the team whether it can continue.
Confirm the schema is at the latest 1.6.x
Before touching the 1.7 artifacts, confirm the running database matches the latest 1.6.x structure. Fineract's documentation states that Liquibase upgrades a database at the latest 1.6.x structure, but fails at startup on older structures, so any older schema must first be stepped up to the latest 1.6.x release. Ask the team to record the current 1.6.x version, the Flyway history table contents and the application image tag. Done means the version and Flyway history match the expected latest 1.6.x state. If they do not, stop here: the rollback point is the untouched production system, and the fix is an intermediate 1.6.x upgrade, not a 1.7 attempt.
Stop write traffic and freeze batch jobs
Put the platform into a controlled window: stop client-facing write traffic, pause scheduled jobs such as the Close of Business Day batch, and confirm no batch run is in progress. Fineract's documentation says Liquibase migrations run only on write instances, so the write node must be the one that carries the upgrade, and no other write activity should race it. Verify by checking that no requests are reaching write instances and that the batch job execution history shows nothing running. Rollback point: traffic can be restored to the 1.6.x instances at this stage without any schema change having occurred.
Take and verify a full database backup
Take a full backup of the Fineract tenant databases and the tenants database, then restore it to a separate PostgreSQL instance and confirm it loads. The restore test matters because the Flyway-to-Liquibase switch changes how the schema is tracked, and an untested backup gives no real rollback. Record the backup identifier, timestamp and checksum in the change record. Done means the restored copy starts against a 1.6.x image and returns the expected record counts for clients, loans and savings. Rollback point: this backup is the restore source if any later step fails after schema changes begin.
Run 1.7 on a write instance so Liquibase applies changes
Deploy the 1.7 image to a single write instance, the only instance type that runs Liquibase migrations according to Fineract's documentation. Keep read and batch instances on the 1.6.x image until the write node is confirmed, so that a failed migration does not leave read or batch paths on a schema they cannot use. On Kubernetes, the liquibase-only profile can run this step as a separate job. Done means the instance reaches a running state and the Liquibase changelog table records the expected changesets. Rollback point: if the migration fails, restore the backup taken in the previous step rather than attempting manual schema edits.
Check startup logs and the leftover Flyway tables
Review the write instance startup logs for Liquibase changeset execution and confirm there are no errors or validation failures. Then inspect the database: Fineract's documentation says the two Flyway tables are left in place after the switch and are not deleted. Confirm both tables still exist, and do not drop them during this upgrade, because they are part of the audit trail for how the schema reached its current state. Done means the logs show a clean migration and the Flyway tables are present and unchanged. Rollback point: a log error or missing changeset returns the team to the backup restore path before any read or batch instance is upgraded.
Roll 1.7 to read and batch instances
After the write instance is healthy, move the read instances to the 1.7 image, then the batch instance, one group at a time. Fineract's documentation describes one write instance, one batch instance and read instances on database replicas, so confirm replicas have caught up with the upgraded primary before pointing read traffic at new nodes. Done means each node reports healthy and the replication lag is within the team's accepted range. Rollback point: any node still on 1.6.x can remain in service while the upgrade is paused, provided the write path has not been left on a mixed schema the older image cannot read.
Run smoke tests on products, accounting and COB
Execute a defined smoke test set before reopening traffic. Cover loan and savings product retrieval, a representative client creation, a loan disbursement and repayment, an accounting journal check and a manual run of the Close of Business Day job on a test copy. Compare results with the pre-upgrade baseline. Done means every case passes and the ledger totals match the baseline. Rollback point: if a test fails in a way that affects money or accounting, reopen traffic only after the team decides between a fix forward and a restore from the verified backup.
Release traffic and keep the rollback window open
Reopen client-facing write traffic and resume scheduled jobs once smoke tests pass and the team has signed off. Keep the verified backup, the 1.6.x image tags and the Flyway tables until the team has run the batch cycle and reconciliation for at least one full business period. Record the final versions, the backup identifier and the test results in the change record. Done means the platform is serving traffic on 1.7 with a documented rollback path until sign-off. Confirm with the team's own release policy how long to retain the backup, since no retention period is set by the project.
Known failure cases when Liquibase starts on an older schema
This is the most predictable failure. Fineract used Flyway until 1.6.x and switched to Liquibase from 1.7.0. Liquibase upgrades a database that already has the latest 1.6.x structure without trouble, but it fails at startup when the schema is older, because the Liquibase changes expect the structure that the latest 1.6.x produces. The fix is to bring the database to the latest 1.6.x first, then start 1.7.0.
- Symptom: the 1.7.0 instance fails during startup while Liquibase runs, before the application serves requests.
- Check: record the release and patch level currently running, then compare the database with the latest 1.6.x structure described in the Fineract documentation.
- Recovery: deploy the latest 1.6.x so its own migrations apply, verify the application, take a backup, and only then start 1.7.0.
- Avoid: hand-editing the schema to get past the error, because that breaks the match between the database and the Liquibase changes.
Confirm the exact 1.6.x patch that your upgrade path requires in the Fineract documentation before you schedule the step.
An interrupted run leaves the database between two states. Liquibase records each changeset as it applies, so a restart should resume from the last recorded point. Whether a failed changeset can be retried safely depends on the change itself and on the database engine, so any partial state should be inspected before the next attempt rather than assumed to be clean.
- Symptom: startup stops with a database error during the Liquibase run, and the application may restart repeatedly or stay down.
- Check: compare the Liquibase tracking records with the changesets in the 1.7.0 release, and look for objects a changeset would have created or altered.
- Recovery: if the state is unclear, restore the pre-upgrade backup and rerun from that clean copy. Clear a lock or a tracking record only after confirming that the schema matches it.
- Concurrency: run migrations on one instance at a time. Liquibase migrations run only on write instances, and on Kubernetes they can run separately with the
liquibase-onlySpring profile, which avoids two pods contending for the same changelog lock. - Instance type: confirm which instance is migrating before you read the logs, because a restarting read or batch instance does not run the migration.
Confirm with the Fineract documentation how the tracking and lock records are handled before you edit them by hand, and keep the pre-upgrade backup until the upgrade is verified.
Local changes to the schema are the least visible cause of failure. Teams sometimes add columns, indexes or tables with local scripts, or install plugins that ship their own migrations. Liquibase does not know about those changes, so a 1.7.0 changeset can try to create or alter an object that already exists or has been changed, and the upgrade then fails in a way that looks like a core defect.
- Symptom: startup fails on a changeset that targets a column, index or table that already exists in a different form, often one added by a local script.
- Check: compare the live schema with a clean database built from the latest 1.6.x, and list every object that Fineract's own changelogs did not create.
- Recovery: move custom schema changes into a separate, versioned migration that your team owns, and restore the core structure before the 1.7.0 upgrade.
- Plugins: ask each plugin vendor or internal team whether it runs its own database migrations, and whether those migrations depend on the Flyway tables left in place after the switch.
- Forks: if core sources were edited, rebase onto the release before upgrading, because changes to core changelogs will not match the release.
Confirm which tables, columns and plugin migrations exist in your database, and test the upgrade on a copy of production before the production run.
What makes this upgrade take longer
The table compares the factors that move effort on a Flyway-to-Liquibase upgrade and what each one changes in the plan. Read each row against your own estimate of your environment, then use the right-hand column as the list of questions to put to a partner before a fixed-scope quote. The main takeaway is that the distance from the latest 1.6.x structure and the state of your staging copy usually matter more than the size of the code change.
| Driver | Why it changes effort | What to ask a partner to scope |
|---|---|---|
| Distance from latest 1.6.x | Databases older than the latest 1.6.x structure fail at Liquibase startup, so each step back adds a prior upgrade stage before 1.7.0. | Which 1.6.x patch level the database is at today, and whether the stepwise path to the latest 1.6.x is in the scope. |
| Number of tenants | Each tenant database has its own schema history, so checks and migrations repeat per tenant and failures can differ between them. | The tenant count, whether every tenant schema is at the same version, and how results are recorded per tenant. |
| Data volume and migration time | Larger schemas and tables take longer to alter, and long-running changes need a window that the business accepts. | Row counts for the largest tables, measured migration time in staging, and the agreed maintenance window. |
| Custom schema changes | Local tables, columns or indexes added outside the project can conflict with Liquibase changesets or be missed in the review. | An inventory of custom database objects and who owns the decision on each one. |
| Write instances and batch jobs | Liquibase runs only on write instances, so the cutover must stop or sequence the write and batch instances around the migration. | The number of write, batch and read instances, the startup order, and the plan for the Close of Business Day job during the window. |
| Staging fidelity | A staging copy that is older, smaller or differently configured than production hides the failures that matter. | Whether staging is a recent restore of production, with the same database platform, tenant list and configuration. |
| Integration and event consumers | Downstream systems reading the database, the API or published business events may need changes or a pause during the upgrade. | A list of consumers, their owners, and the test evidence each team needs before sign-off. |
| Leftover Flyway tables | The two Flyway tables remain after the switch, so cleanup and monitoring rules must be decided rather than assumed. | Whether the scope includes documenting the leftover tables and the rule for removing them later. |
Questions teams ask before upgrading Fineract from 1.6 to 1.7
What drives the cost of a Fineract 1.6 to 1.7 upgrade?
The cost depends mostly on how far the database sits from the current 1.6.x structure, how much custom code and integration touches the schema, and how many environments need the change. A plain schema switch on a clean, recent 1.6.x database is the cheapest case. Costs rise when the database must first be stepped up to the latest 1.6.x, when custom SQL or extensions depend on Flyway-era objects, and when staging, testing and rollback rehearsals must be repeated. Ask any partner for a quote that lists the environment count, the testing scope and whether the work is fixed-scope, and separate one-time upgrade effort from any ongoing support retainer.
How long does the upgrade take?
Duration is driven by the same factors as cost: the starting schema version, the size and shape of the database, the number of customizations and integrations, and how much regression testing the business requires before go-live. Fineract's documentation describes the Liquibase switch as seamless when the database already has the latest 1.6.x structure, so that case takes less time than one that needs a prior upgrade step. Confirm the schedule against your own staging copy of the database, because the first run on a real copy usually reveals the timing that matters. Ask for milestones tied to environments rather than a single end date.
What does the upgrade need from our internal team?
Your team needs to own the decisions that only the institution can make, and to provide access to the systems the upgrade touches. Typical needs include a database administrator who can take and restore backups, an engineer who knows the deployment and its configuration, someone who owns the products, accounting and end-of-day processes for testing, and a change approver for each environment. Expect to supply staging hardware or cloud capacity that mirrors production. The effort is smaller if these roles are named and available during the upgrade window.
Can we do the Fineract 1.6 to 1.7 upgrade in-house?
Yes, an experienced platform team can run this upgrade in-house if it has PostgreSQL administration skills, the ability to read Liquibase changelogs, and a tested backup and restore process. The steps are known and the project documents the switch. The risk sits in the surrounding work: validating accounting, end-of-day processing and integrations after the change, and proving rollback. Many teams choose a partner for the parts they have not done before, such as repeated rehearsals or independent regression checks, and keep the production change under their own control. Decide this by comparing your team's time and skills against the scope in writing.
What happens to the Flyway tables after the upgrade?
The two Flyway tables stay in the database after the switch to Liquibase, because Fineract does not delete them. They no longer control schema changes, so leaving them in place is expected rather than a sign of failure. Do not drop them as part of the upgrade. Record their presence in your change documentation so that auditors, database administrators and future engineers do not mistake them for an active migration tool. Any cleanup should be a separate, reviewed change made after the upgrade has been stable for long enough to satisfy your own rollback policy.
What should we do if our schema is older than 1.6.x?
Do not run the 1.7 upgrade directly. Fineract's documentation states that Liquibase upgrades a database at the latest 1.6.x structure, but fails at startup on older structures, so the database must first be upgraded to the latest 1.6.x. Plan that as a separate step, test it in staging, and confirm the application version that matches each stage. Keep a verified backup before each step. If your schema is much older, consider the broader sibling guidance on upgrading old 1.x releases, since older installations often carry custom changes that need their own review.
Which failure cases should we test before go-live?
Test the failures that are most likely to block a rollout or corrupt data. Start with startup failure on a database that is not at the latest 1.6.x structure, since that is the documented failure mode. Next, check that the application starts cleanly after the Liquibase run, that tenant connections resolve, and that products, accounting postings and the end-of-business-day job behave as before. Also verify that a restored backup returns to the prior state, and that any custom SQL or integration still reads the expected tables. Record the results so you can show them to your change approvers.
What a DeployOpen upgrade engagement covers
A DeployOpen upgrade engagement for the move from Fineract 1.6 to 1.7 starts with a written scope. In the scoping phase we inventory the current database, including whether it is already on the latest 1.6.x structure, and we document every custom change that touches the schema, such as added tables, altered columns, custom Spring Batch jobs or direct SQL run against Fineract tables. We also confirm the Flyway history in the database, the Java and container versions in use, and which instances write to the database. The output is a scope document that lists each item in or out of the engagement, the environments covered, and the acceptance tests the upgrade must pass. The written scope and the quote follow from that document, so the reader sees the same deliverables and exclusions the engagement team will work to.
Execution follows a staging rehearsal. We restore a recent copy of production data into an isolated environment, run the upgrade with the same images and configuration planned for production, and record each Liquibase changeset, the run time and any warnings. Checkpoints sit before the schema change, after it, and after functional checks on products, accounting and business-date handling. Rollback planning covers a verified database backup taken immediately before the cutover, the decision point after which rollback is no longer simple, and the steps to restore the previous image. The handover pack includes the runbook, the rehearsal log, the list of leftover Flyway tables and the operating notes for your team. Ongoing support, upgrades and testing for later releases are available as a DeployOpen retainer, which is priced separately from this fixed-scope work.
How DeployOpen scopes, delivers and supports Fineract upgrades
DeployOpen approaches the Apache Fineract 1.6 to 1.7 upgrade as a controlled schema change, starting with a check of your current database structure against the Flyway-to-Liquibase switch. We plan, build and document the upgrade in your own infrastructure, then hand over the evidence and runbooks your team needs to run it again.
How we scope
- Written scope confirms your current Fineract version, database platform and whether the schema is already at the latest 1.6.x structure.
- Scope covers the upgrade path, environments to be upgraded, rollback approach and the regression tests your team needs to sign off.
- Engagements are fixed-scope, so deliverables and timelines are agreed in writing before any upgrade work starts.
How we build
- We run the upgrade first against a copy of your production schema in a staging environment you control.
- We check the Flyway history and the two leftover Flyway tables, and document how each is treated after Liquibase takes over.
- We record each failure case we find, with the exact startup error, the fix applied and the test that confirms it is closed.
How we hand over
- You receive a written runbook with pre-upgrade checks, the ordered upgrade steps, validation queries and the rollback procedure.
- Handover includes test evidence from the staging run so your team and auditors can see what changed and how it was verified.
- We walk your platform and database staff through the runbook so they can repeat the steps in later upgrades without us.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer, covering later Fineract releases and schema changes.
- Support can include reviewing Fineract release notes and planning the next upgrade stop against the project's quarterly release cadence.
- Ask in your quote which environments, backup checks and post-upgrade testing are included in the retainer and which need separate scope.
