Which database should you run Apache Fineract on?
For a new Apache Fineract deployment, start on PostgreSQL. The Fineract README names PostgreSQL as the recommended database, and MariaDB and MySQL are both marked deprecated under proposal FSIP-9, which standardizes the project on PostgreSQL. Deprecated does not mean unsafe, but it does mean MariaDB and MySQL are no longer the path the project tests, documents and packages by default, so every upgrade, driver change and troubleshooting question will land on a database the community is moving away from. Staying on MariaDB is a defensible choice only when it is deliberate and time-boxed. The strongest reasons are operational: your team already runs MariaDB well, you depend on Galera synchronous multi-primary clustering or MariaDB-specific features, or you have a standard MariaDB estate with backup and monitoring already in place. In that case, write down the target date for a move, confirm with your own infrastructure team which MariaDB release line you will stay on, and check the support windows published by the MariaDB Foundation against your planned migration date. If none of those reasons apply, a fresh install on MariaDB adds a migration you will have to pay for later.
If you are already on MariaDB or MySQL, plan the move as a project rather than a driver swap. Fineract does not ship the MySQL or MariaDB JDBC driver in its official Docker image, so you must supply it yourself and override the default database settings, and that setup becomes a recurring item in each release. Before you schedule the cutover, ask your implementation partner or internal team to confirm the migration path for your Fineract version, the data volume, the tenants database, and the rollback plan. The Fineract documentation also notes that Liquibase migrations run only on write instances, which matters when you rehearse the switch. Treat the rehearsal as the deciding test: if the migrated copy passes your reconciliation and reporting checks, the move is ready.
PostgreSQL and MariaDB or MySQL for Fineract, factor by factor
This table compares PostgreSQL and MariaDB or MySQL for running Apache Fineract across licensing, official status, driver packaging, release windows, replication and what your team must add. Read each row against your own compliance, support and operating constraints, since the facts favor PostgreSQL on official status and packaging while MariaDB offers its own replication and clustering features.
| Factor | PostgreSQL | MariaDB or MySQL |
|---|---|---|
| License | PostgreSQL License, a permissive license similar to BSD or MIT | MariaDB Server is GPLv2; confirm how GPLv2 terms fit your distribution and policy |
| Official status in Fineract | Recommended database under the Fineract README | Deprecated under FSIP-9; the README asks users to override settings themselves |
| JDBC driver in official Docker image | PostgreSQL JDBC driver included | Not included; you must download the driver and override database settings |
| Major release support window | Each major version supported for 5 years after initial release (PostgreSQL versioning policy) | LTS community binaries supported 3 years after GA, then 2 more years for critical and security fixes |
| Replication and high availability | Hot standby, synchronous and asynchronous replication; logical replication across major versions | Asynchronous, semi-synchronous and parallel replication, plus Galera synchronous multi-primary clustering |
| Automatic failover | Not provided by PostgreSQL itself; external tools required | Clustering features cover failover; confirm the approach for your chosen topology |
| What your team must add | Failover tooling, backup and point-in-time recovery setup, connection pooling such as PgBouncer | Driver management, Fineract configuration overrides, and confirmation of Fineract behavior on your chosen version |
Why the official image only works out of the box with PostgreSQL
The official Fineract Docker image includes only the PostgreSQL JDBC driver. The MySQL and MariaDB drivers are not bundled because of license incompatibility, so a team that runs Fineract on MariaDB or MySQL cannot simply pull the image and point it at a database. The Fineract README tells those users to download the JDBC driver themselves and override the default database settings. In practice, that means the team must place a driver that matches its database version into a custom image, then set the datasource properties, such as the JDBC URL, username and password, so the write and batch instances connect to the right database. Confirm the exact driver version and property names against the Fineract README and the platform documentation for the release you plan to deploy before you write the build.
This is recurring build and release work, not a one-time setup. Each time the team moves to a new Fineract release, it must rebuild its image, confirm the driver still loads, retest the database connection, and re-verify the settings it overrode. Fineract publishes official releases quarterly, so that cycle repeats several times a year. The same applies to the driver itself, which the team must track for security fixes and compatibility with the MariaDB or MySQL server version it runs. Ask your DeployOpen or in-house platform owner to name who owns the image pipeline, who approves a driver upgrade, and how a failed build is handled before a production change window. Teams that standardize on PostgreSQL avoid this loop entirely, which is the practical reason the deprecation matters for operating cost.
How an existing MariaDB installation should plan a move
This sequence turns an existing MariaDB-backed Fineract deployment into a tested PostgreSQL deployment with a documented cutover and a rollback path. Each step ends with a check the team can verify before moving on.
Inventory the current versions and dependencies
The platform or infrastructure owner records the exact MariaDB server version, the Fineract release and image tag in use, and the MySQL or MariaDB JDBC driver and database settings that the deployment overrides. The team also lists every system that reads from the database, including reporting jobs, batch instances, read replicas, backup tooling and any integration that connects directly with SQL. The step is done when this inventory is reviewed by the application owner and the database administrator, and any connection that bypasses the Fineract API is flagged for separate review.
Confirm the MariaDB lifecycle for the release line
The database owner checks the MariaDB Foundation's published notes for the release line in use, since long-term releases receive community binaries for a fixed period followed by critical and security fixes only, and rolling releases end on a shorter cycle. The team should confirm the end-of-life date for its specific line with the Foundation's current announcements rather than relying on memory or older blog posts. The step is done when the team has written down the support end date for its current line and the date by which it must have moved, so the migration plan has a documented deadline driver.
Stand up a PostgreSQL copy with the driver
The platform engineer builds a non-production environment that matches the production Fineract version and deploys it against a PostgreSQL server, using the official image, which ships the PostgreSQL JDBC driver. The team confirms that database settings, tenant definitions in the tenants database and the Liquibase migration path work on an empty schema before any data is loaded. The step is done when the application starts cleanly, the migrations complete on write instances, and an administrator can log in and reach the API health endpoint.
Rehearse the data move on the copy
The database administrator loads a recent copy of production data into the PostgreSQL environment using a conversion method the team has scoped and tested for MariaDB-to-PostgreSQL movement, which is a different exercise from a PostgreSQL major version upgrade. Type differences, character sets, sequence values, decimal precision and date handling are checked table by table, and the team records every row count and any transformation it needed. The step is done when the rehearsal completes end to end and each discrepancy has an agreed fix or an explicit accepted exception.
Validate balances, reports and tenant data
Finance and operations staff compare account balances, loan schedules, savings positions, journal entries and client records between the MariaDB source and the PostgreSQL copy, using reports that the business relies on. The team also runs the reporting jobs, tenant-specific configurations and any batch processes against the copy and compares outputs. The step is done when the business owner signs off on a written reconciliation that covers every product and tenant in scope, with differences explained.
Plan cutover with a rollback path
The team schedules a cutover window, freezes writes on the MariaDB source, performs a final data load, and switches the application configuration to the PostgreSQL database. The plan must state who can call the rollback, what triggers it, and how transactions written after cutover would be handled if the team returns to MariaDB, because a rollback that loses posted entries is not a rollback. The step is done when the runbook has been rehearsed once and the rollback decision criteria are approved in writing by the operations and business owners.
Retain the source and confirm post-cutover operations
After cutover, the team keeps the MariaDB source read-only for an agreed retention period and verifies backups, restore tests and monitoring on the PostgreSQL side, including replication, failover and point-in-time recovery choices, which PostgreSQL leaves to external tooling for automatic failover. The team confirms that the PostgreSQL support window for the chosen major version is recorded in its maintenance calendar. The step is done when a restore from the new backups has been tested and the decommissioning date for the MariaDB source is recorded in the change log.
Which path fits which team
If you are deploying Apache Fineract with no existing database, PostgreSQL is the direction to take. The project's README names PostgreSQL as the recommended database, and the official Docker image includes the PostgreSQL JDBC driver, so you avoid driver packaging work from day one. Your choice is then about operating PostgreSQL well in your own infrastructure.
- Driver packaging: The official image ships only the PostgreSQL JDBC driver, so the standard image runs without extra driver files.
- Support window: PostgreSQL 18 is supported until November 14, 2030, and PostgreSQL 17 until November 8, 2029, which gives you a long planning horizon.
- Replication: Hot standbys support read-only queries, and you can choose synchronous or asynchronous replication.
- Failover: PostgreSQL does not detect a primary failure on its own, so you must select, deploy and test an external failover tool.
- Read scaling: Fineract's documentation recommends one write instance, one batch instance and several read instances on read replicas for high load.
The main condition that would change this is an existing organizational standard for MariaDB or MySQL that your operations team cannot waive. Confirm with your Fineract release notes which PostgreSQL versions the release is tested against, and plan connection pooling before you size the database tier.
If Fineract already runs on MariaDB and you have DBAs who know it well, you have two workable paths: keep MariaDB with the setup the project requires, or plan a migration to PostgreSQL on your own schedule. The recommended direction for a stable estate is to plan the move while keeping MariaDB supported. The README says MariaDB users must download the JDBC driver themselves and override the default database settings, so that work becomes permanent ownership on your side if you stay.
- Staying on MariaDB: Document the driver version, the override settings and who maintains them in your change records.
- Version position: MariaDB 12.3 is an LTS release with a GA date of May 28, 2026, alongside maintained LTS lines 11.8, 11.4 and 10.11. Check which line you run, and note that 13.0 is a rolling release with community end of life in Q4 2026.
- Migration tooling: PostgreSQL documents pg_dumpall with restore, pg_upgrade and logical replication for upgrades, and logical replication works between different major versions. Those options are for PostgreSQL-to-PostgreSQL moves, so your data migration path needs its own test.
- Skill transfer: Your DBAs will need to learn PostgreSQL backup, replication and failover tooling, and that time should appear in your plan.
The condition that would change this direction is a MariaDB version that falls outside your support needs or a migration window you cannot staff. Confirm with the Fineract project and your DBAs which schema version you run and whether a restore into PostgreSQL has been tested end to end.
If Fineract runs on MySQL, treat the move to PostgreSQL as a migration project, not a routine version upgrade. The README marks MySQL as deprecated under FSIP-9, and the official image does not include a MySQL driver because of license incompatibility. Your team would supply and maintain that driver, which is a recurring cost and a point of failure that PostgreSQL deployments avoid.
- Deprecated status: Both MySQL and MariaDB are deprecated for Fineract, so new work should not start on MySQL.
- Driver ownership: You download the driver, place it in your build, and override the default database settings, then repeat that work at every Fineract upgrade.
- Compatibility assumptions: Do not assume that behavior validated on MariaDB carries over to MySQL. Ask the Fineract project which MySQL versions were last tested, if any.
- Data migration: Schema and data type conversion between MySQL and PostgreSQL needs a full staging restore and reconciliation of balances, dates and identifiers.
- Vendor terms: Confirm your MySQL vendor's support dates in writing, since this page does not state them.
The main condition that would change this direction is a dependency that only works on MySQL and cannot move in your timeline. Confirm with your Fineract support provider or the project which migration path has been validated for your schema version before you set a cutover date.
In a regulated environment, the database choice is a change that must be justified, approved and traceable. PostgreSQL is the direction that matches the project's own recommendation, and FSIP-9 gives your change board a documented, public rationale. Your change record should show the decision, the alternatives considered, the test evidence and the rollback plan, so the reviewer can follow each step.
- Decision record: Cite the README's statement on deprecation and FSIP-9 in the change request, and record which databases you evaluated.
- Licensing review: The PostgreSQL License is a permissive license similar to BSD or MIT, while MariaDB Server is licensed under GPLv2. Have counsel confirm what those terms mean for your use.
- Migration control: Liquibase migrations run only on write instances, so name the instance that runs them and document the liquibase-only Spring profile if you run on Kubernetes.
- Evidence: Keep restore test results, version pins and the upgrade cadence. Fineract releases quarterly, and PostgreSQL minor releases come at least once every three months.
- Assessment boundaries: DeployOpen can prepare the systems, controls and evidence. Independent auditors and certification bodies decide whether that evidence meets your requirements.
The condition that would change this is a regulator, auditor or internal standard that already approves a specific database. Ask your assessor which evidence they expect and whether your change board requires formal risk acceptance for any deprecated component still in service.
What running PostgreSQL under Fineract requires
Fineract standardizes on PostgreSQL, so the database version policy, upgrade path, replication design and authentication model become part of the platform you run. The cards below cover what your team must plan, check and own once PostgreSQL is the database under your core banking system.
Pick a supported major version
Supported PostgreSQL majors have different end dates: 14 runs to November 12, 2026, 15 to November 11, 2027, 16 to November 9, 2028, 17 to November 8, 2029 and 18 to November 14, 2030. A new Fineract deployment should start on a major still inside its window with room for the planned go-live and operating period. Check which major your Fineract release and your DBA standards expect, and put the end-of-support date on the upgrade calendar from day one.
Apply minor updates with restarts
Minor PostgreSQL releases do not change the internal storage format, so applying one means replacing the executables and restarting the server. Your team still has to schedule a maintenance window for each restart, test the Fineract write and batch instances against the new binaries, and confirm that the image or host tooling you use applies the patch consistently across environments. Ask your platform or DBA lead who owns this cycle and how often it runs.
Plan major upgrades in advance
Major upgrades use pg_dumpall with restore, pg_upgrade, or logical replication. Logical replication can limit downtime to several seconds, but it needs careful setup and validation of the Fineract schema, including Liquibase state. Pick the method during planning, rehearse it on a copy of production data, and record the rollback path before the change window opens.
Design replicas for read load
PostgreSQL supports hot standby servers that serve read-only queries, with either synchronous replication, where a commit waits for standbys, or asynchronous replication. Fineract's documented pattern uses one write instance, one batch instance and several read instances on read replicas for high load. Choose synchronous or asynchronous mode based on how much data loss your financial records can tolerate, and confirm that read-only instances do not run writes or migrations.
Add external failover tooling
PostgreSQL does not detect a primary failure and notify the standby on its own, so automatic failover needs external tools. Your team must select, deploy, test and operate that tooling, along with the connection routing that points Fineract at the new primary. Ask whether the failover design has been exercised against Fineract's write instance and whether the runbook covers batch jobs that were running at the time of failure.
Choose modern authentication methods
PostgreSQL documents password, GSSAPI, SSPI, LDAP, RADIUS, certificate, PAM and OAuth methods. PostgreSQL 18 adds an OAuth 2.0 method and deprecates MD5 password authentication in favor of SCRAM. Set password_encryption to SCRAM and confirm that the Fineract database account, the tenants database and any service accounts all authenticate with SCRAM or certificates. Confirm the driver version in your Fineract build supports the method you select.
Questions teams ask before moving Fineract off MariaDB
Can our team migrate Fineract from MariaDB to PostgreSQL ourselves?
Yes, a capable team can, but the work is more than a database dump and restore. The migration touches the schema, the JDBC configuration, the tenants database, and every environment that connects to Fineract. Your team needs enterprise Java skills to rebuild and configure the application, database administration skills for PostgreSQL, and someone who understands your core banking data well enough to test reconciliation after cutover. The Fineract README notes that a proper production deployment can be complex, costly and time-consuming and may need enterprise Java skills or a vendor, so check honestly whether those skills sit in-house today.
What drives the cost and effort of a Fineract database migration?
The main drivers are the number of environments, the data volume, the custom reports, the number of tenants, and how deep the testing goes. Each environment, from development through production, needs its own rebuild, data load and verification. Custom reports and any integrations that query the database directly must be rewritten or retested against PostgreSQL. Multi-tenant setups add work because each tenant's connection and data must be validated. Cost is mostly people time: internal engineers, a database administrator, and any partner you hire. Ask a partner to price each driver separately in a written scope so you can see which ones you can reduce.
How long does a Fineract move to PostgreSQL take?
No reliable duration can be stated from the sources available, and the length depends on your environment, not on a generic rule. The timeline is set by data volume, how many environments need rebuilding, the scope of custom reporting and integrations to retest, the depth of reconciliation testing, and how much cutover rehearsal your risk appetite requires. Ask any partner for a written scope that lists each phase, its entry and exit criteria, the environments covered, the testing approach, and the dates they commit to. A fixed-scope agreement with agreed deliverables makes the timeline easier to compare across bids.
Can we keep running MariaDB with Fineract, and for how long?
MariaDB can keep running for now, but Fineract's README marks MariaDB and MySQL as deprecated under FSIP-9, and the official Docker image includes only the PostgreSQL JDBC driver. If you stay on MariaDB, you must download the JDBC driver yourself and override the default database settings, and you carry that maintenance on every upgrade. For MariaDB's own support horizon, check the MariaDB Foundation's release windows: new long-term releases are announced yearly with community binaries supported for 3 years after GA, plus 2 more years of critical and security fixes. Compare that against the Fineract releases you plan to run, since Fineract's release notes will show when deprecated paths stop being tested.
Does PostgreSQL failover need extra tooling beyond replication?
Yes. PostgreSQL supports hot standby servers that serve read-only queries, along with synchronous and asynchronous replication, but it does not include software that detects a primary failure and promotes a standby. Automatic failover requires an external tool or orchestration layer that you select, deploy, test and operate. Your design choices include whether commits must wait for standbys (synchronous replication, which trades write latency for durability) and how connections are redirected after promotion. Connection pooling with PgBouncer is often part of this design. Confirm the failover approach in your written scope, and test it under realistic failure conditions before go-live.
When should we bring in an outside partner for this migration?
Bring in a partner when your team lacks the Java, PostgreSQL or banking reconciliation skills to carry the work safely, or when the cutover window cannot absorb trial-and-error. DeployOpen plans, implements, customizes, integrates, hardens, backs up, upgrades, documents and supports self-hosted open-source platforms inside your own infrastructure, and most engagements are fixed-scope with scope, deliverables and timelines agreed in writing before work starts. DeployOpen does not publish a price list, so ask for a quote that follows from the written scope. Ask any firm to name who will own data validation, rollback and post-cutover support.
Upgrades, backups and monitoring on each database
This table compares how each database handles upgrades, backup and point-in-time recovery, replication and failover, and monitoring for a Fineract deployment. Read each row as a question to answer in your own environment, since the documented tooling sets the baseline but your runbooks, hosting and staffing decide the result.
| Operational area | PostgreSQL (Fineract's standard) | MariaDB or MySQL (deprecated for Fineract) |
|---|---|---|
| Minor version updates | Minor releases do not change the storage format, so updating means replacing executables and restarting the server | Confirm the minor update path and driver compatibility with your MariaDB or MySQL version and the Fineract release you run |
| Major version upgrades | Documented options include dump and restore, pg_upgrade, or logical replication, which works across major versions with only several seconds of downtime | Confirm the supported upgrade procedure for your MariaDB line, since MariaDB releases follow a separate long-term and rolling schedule |
| Continuous archiving and point-in-time recovery | PostgreSQL documents continuous archiving with base backups and WAL archiving for point-in-time recovery; confirm the tooling you choose and test restores | Confirm the backup and point-in-time recovery method for your engine and storage engine, and test restores in your environment |
| Replication | Hot standby servers serve read-only queries, with synchronous or asynchronous replication available | MariaDB offers asynchronous, semi-synchronous and parallel replication with global transaction IDs, plus Galera multi-primary clustering |
| Automatic failover | PostgreSQL does not detect primary failure or notify standbys itself, so you need an external failover tool and must test it | Confirm which failover mechanism applies to your topology, including Galera or replication manager tooling |
| Connection management | Confirm pooling needs with your team, for example PgBouncer, alongside Fineract's read and write instance pattern | Confirm how your connection pooling and read routing handle Fineract's read and write instance types |
| Monitoring and staffing | Teams need PostgreSQL operations skills for replication, backups and failover; confirm the monitoring stack and alert ownership | Teams need MariaDB operations skills and must keep a JDBC driver and overrides under their own control, since the official image does not ship one |
| Vendor support and ownership | Ask your implementation partner which runbooks, backup tests and failover drills are in scope and who owns them after handover | Confirm who supports the database and the custom driver setup for the lifetime of the deployment |
Where DeployOpen fits in a database move
DeployOpen plans, implements, hardens, backs up and documents self-hosted platforms inside your own infrastructure, and a database move is usually scoped that way too. For a Fineract deployment, that means the work covers the pieces this topic turns on: the database driver packaging, the datasource and tenant connection settings that point Fineract at the database, the Liquibase migration path, the backup and restore routine, and the runbook your operations team will follow afterward. DeployOpen does this work in your cloud accounts, data centers or air-gapped network, so the database stays under your control throughout.
A move from MariaDB or MySQL to PostgreSQL is normally agreed as a fixed-scope engagement. Before work starts, both sides should write down which environments are in scope (development, test, production and the tenants database), which data migration method will be used, how cutover and rollback will be run, and which deliverables will be handed over, such as configuration records, test evidence and updated operating documentation. Ask for the scope, deliverables and timeline in writing, and ask what is excluded, for example application code changes or licensing of any database engine. Confirm with your own team whether any compliance evidence needs to come out of the change, and confirm with the independent auditor, if one applies, what they will expect to see.
How DeployOpen scopes and delivers a Fineract database move
DeployOpen plans, implements, hardens, documents and supports self-hosted open-source platforms inside the client's own infrastructure. For Apache Fineract, that means treating the database choice as a scoped change to a running system, with the migration path, testing and evidence agreed in writing before any work begins.
How we scope
- Confirm which database each Fineract environment runs today, including tenants, read instances and any MariaDB or MySQL driver overrides.
- Agree in writing whether the target is PostgreSQL, with the migration path, cutover window and rollback steps set out as deliverables.
- Ask for a written quote that separates the assessment, migration, testing and documentation work, so each cost component is visible.
How we build
- Build the database connection configuration, JDBC driver packaging and Liquibase migration runs against a copy of your environment first.
- Test tenant connections, read replica behavior and batch jobs on the target database before any production data is moved.
- Document each configuration key, image change and verification step so your team can repeat the process on other environments.
How we hand over
- Deliver runbooks for the cutover, rollback and post-move checks, written so your operations staff can follow them without us.
- Walk your team through the new backup and restore procedure, and record which PostgreSQL version and settings were deployed.
- Provide evidence of testing and configuration for your own assessors, while leaving any audit or certification to independent bodies.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers, scoped separately from the migration project.
- Retainers can cover PostgreSQL minor updates and future Fineract release upgrades, with the work agreed in writing.
- Confirm with us during scoping which responsibilities stay with your team and which sit under a retainer or a later engagement.
