Why backup and restore for Apache Fineract databases needs its own plan
A backup of a Fineract deployment is only usable if it captures every database that holds its state. Apache Fineract is multi-tenant. Requests carry a Fineract-Platform-TenantId header, and the platform looks up each tenant's connection details in a tenants database, while each tenant keeps its own data in a separate schema. Client records, loan and savings accounts, ledger postings and job history all live in PostgreSQL, which the project's README names as the recommended database. A dump that captures one tenant schema but misses another, or that omits the tenants database, may restore cleanly yet leave a tenant unreachable or its accounts inconsistent. Your plan should therefore start with an inventory: list the tenants database, every tenant schema, and any other database your deployment writes to, then confirm the exact schema names and connection settings in your own environment before choosing tools.
Teams usually need this work at three points: before go-live, when the first real client and ledger data arrives; before every Fineract upgrade, because a failed migration is the moment a known-good restore point matters most; and whenever a regulator, auditor or internal risk function asks how the institution would recover core banking data. The third point depends on your jurisdiction and your own risk policy, so confirm the recovery expectations with your compliance and risk owners instead of assuming them. Decide early who owns the backup schedule, who can trigger a restore, and where copies are held. Those answers shape the recovery point and recovery time you can commit to, and they determine whether a managed PostgreSQL service or a self-run cluster fits your infrastructure.
Logical dumps versus continuous archiving and point-in-time recovery
A logical dump uses pg_dump to export one database as SQL or a custom archive, and pg_dumpall to export the whole cluster, including global objects such as roles. The output is a snapshot of the data at the moment the dump ran, and it is rebuilt by replaying statements into a fresh server. Restore time grows with data volume because every row and index must be recreated, and the restored data can only be as recent as the last successful dump.
- Recovery granularity: You recover to the time of the dump, not to any moment between dumps. Transactions committed after the last dump are lost unless the application can replay them.
- Restore time: Restores rebuild indexes and constraints from scratch, so duration depends on data size and hardware. Ask the database team to measure a restore of a production-sized copy rather than relying on general estimates.
- Object scope:
pg_dumphandles one database at a time, so each database in the cluster needs its own dump unless you usepg_dumpall. - Upgrade suitability: Dumps are a standard route for a major version upgrade, because the restore is performed by the newer server binaries.
- Operational footprint: Dumps need little setup, but they run as a load on the source database and the output files need their own retention and encryption controls.
Before relying on dumps, confirm the dump schedule against your acceptable data loss window and test that a restore completes within your recovery time target.
Continuous archiving combines a base backup of the data directory with a continuous stream of write-ahead log (WAL) segments copied to an archive location. Together they allow the server to be restored to the state of the base backup and then replayed forward, either to the end of the archive or to a specified point in time. The PostgreSQL continuous archiving documentation describes this as the basis for point-in-time recovery (PITR).
- Recovery granularity: You can choose a target time, transaction or restore point and stop replay there, which is useful when a faulty batch job or a bad repair transaction changed balances.
- Restore time: Restore duration includes copying the base backup and replaying WAL, so it depends on how much WAL must be applied. Frequent base backups shorten replay.
- Whole-cluster scope: The archive covers every database in the cluster at once, including the tenants database and every tenant schema, which keeps them consistent with each other.
- Disaster recovery suitability: Archives are a strong fit for recovering from corruption, operator error or loss of a site, provided the archive is stored separately from the primary.
- Operational footprint: Archiving requires configuration of
archive_modeandarchive_command, monitoring of archive lag and storage, and regular base backups.
Confirm the archive destination, the retention period and the recovery steps with your database administrator before go-live.
Fineract is multi-tenant. Tenant connections are configured from a tenants database, and each tenant has its own schema holding that tenant's data. A recovery therefore has to bring the tenants database and every tenant schema back to a single consistent point. Restoring one tenant from a separate dump while others are at a different time can leave the tenant registry pointing at the wrong state, and it can cause reconciliation problems between tenants that share services or reports.
- Single cluster view: A cluster-level base backup with WAL archiving restores all databases and schemas to the same moment, which is the simplest way to keep tenants aligned.
- Per-database dumps: If you dump each database separately, take the dumps in a documented order and record the time window, because they are not taken at one exact instant unless you coordinate them.
- Tenant-level restore: Restoring a single tenant schema from a dump is possible, but it must be checked against the tenant registry and any cross-tenant references your team maintains.
- Verification: After any restore, confirm tenant connection settings, the tenant list and sample balances in each tenant against your reference reports.
Confirm with the Fineract administrator exactly which databases and schemas hold tenant state in your deployment, and test a restore that brings all of them back to one point.
The two approaches serve different purposes. A logical dump is well suited to moving data into a newer PostgreSQL major version, while continuous archiving is designed for restoring a damaged or lost system to a recent point. PostgreSQL documents several upgrade routes, including dump and restore, pg_upgrade, and logical replication, which can allow a major upgrade with only several seconds of downtime. Those routes are upgrade tools, not replacements for a disaster recovery archive, so keep a PITR archive running through and after any upgrade.
- Upgrade rollback: Keep the old cluster and its archive intact until the new version has run through your acceptance tests, so you can return if needed.
- Logical replication: It works between different major versions, but it needs its own setup and monitoring, and it does not replace a backup.
- Disaster recovery: An archive stored in a separate account, region or site is the basis for recovering from loss of the primary environment.
- Restore testing: Schedule restores of both the dump files and the PITR archive into an isolated environment, and record how long each took.
- Version currency: Check the supported PostgreSQL major versions in the official versioning policy when you choose the target version for the upgrade.
Confirm the recovery point objective and recovery time objective for your Fineract system, then ask your team to show which method meets each target.
Which backup method fits which recovery need
This table compares four PostgreSQL protection methods against the failures a Fineract tenants database and its tenant schemas can face. Read each row as a question: what event would you need to recover from, and does the method cover it? The main takeaway is that a standby replica keeps the service available but does not protect against logical errors or deletions, so it never replaces a restorable backup.
| Method | What it protects against and what it does not | Restore granularity | When it fits |
|---|---|---|---|
| Logical dumps (pg_dump, pg_dumpall) | Protects against accidental table or schema damage and supports moving data between PostgreSQL versions. Does not capture changes made after the dump, so recent transactions are lost on restore. | Whole database, single schema or single table. Each tenant schema can be dumped separately, but the tenants database must be captured too. | Smaller databases, restores into a different PostgreSQL major version, and per-tenant recovery. Confirm the dump time window against your loss tolerance. |
| Base backups with WAL archiving (continuous archiving) | Protects against host loss, storage failure and corruption, and supports point-in-time recovery to a moment before a bad transaction. Does not protect against a faulty change that was archived before anyone noticed, and needs archive monitoring to be trusted. | Whole cluster to any archived point in time. Restoring a single tenant schema alone is not the normal path and needs its own test. | Core banking production systems where recent transactions must be recoverable. Test the restore regularly and confirm archive retention with the business. |
| Managed PostgreSQL snapshots (where the platform offers them) | Protects against instance or volume loss when the provider's snapshot and recovery features are in use. Does not necessarily cover every tenant database or logical error, and recovery points depend on the provider's settings. | Usually whole instance or volume. Confirm whether point-in-time recovery is offered and whether it covers all Fineract databases. | Fineract hosted on a managed service where the provider documents its backup and recovery behavior. Verify what the provider includes, retention and restore steps in writing. |
| Standby replicas (hot standby, synchronous or asynchronous) | Protects against primary host failure by letting service continue on another server. Does not protect against deleted rows, bad batch runs or corrupted data, because those changes replicate to the standby. | None for recovery purposes. A standby reflects the primary state, including damage, so it cannot roll back a mistake. | High availability and read scaling for Fineract read instances. Pair every standby with one of the backup methods above. |
Setting up backups that cover every tenant and prove they restore
This sequence takes a Fineract database estate from unprotected to a backup set that covers the tenants database and every tenant schema, with copies stored off the primary host and a first restore confirmed in an isolated environment.
Inventory the tenants database and every tenant schema
Start by listing the tenants database and every tenant database or schema that Fineract connects to, using the tenant entries in that database as the source of truth. Record each schema name, its size, the instance that writes to it, and any read replica attached to it. Confirm with your platform team whether any tenant uses a separate database server, because a backup job that covers only the default database will miss those tenants. The step is done when the inventory matches the tenant list in the running environment and someone other than the author has reviewed it.
Enable WAL archiving to a tested destination
Turn on continuous archiving for each PostgreSQL cluster that holds Fineract data so that write-ahead log segments are shipped to a separate archive location. Follow the PostgreSQL continuous archiving documentation for the archive_mode and archive_command settings, and confirm the archive destination is reachable from the database host and writable only by the backup account. Force a log switch and check that the segment appears at the destination. The step is done when a manually triggered segment is archived successfully and the archive failure alert is wired to your monitoring.
Schedule base backups and logical dumps
Configure a base backup for each cluster so that point-in-time recovery has a starting point, and schedule logical dumps of the tenants database and each tenant schema as a second, independent copy. The database team owns the schedule, and the dumps should run with a consistent snapshot so tenant schemas are captured at the same point. Record the start time, end time, and exit status of each job. The step is done when one scheduled run of each job completes without error and the output lists every tenant schema from the inventory.
Encrypt copies and store them off the primary host
Encrypt every base backup, WAL archive and dump before it leaves the database network, using keys held in your key management service rather than on the database server. Copy the encrypted files to storage in a separate failure domain, such as another account, data center or object storage bucket, with write-once or versioned retention where your platform supports it. Restrict read access to the restore role and log every retrieval. The step is done when a copy is present off the primary host, decrypts with the documented key procedure, and the access log shows who can read it.
Record configuration and versions with each backup
Store the Fineract image tag or WAR version, the PostgreSQL major and minor version, the Liquibase state, the tenant inventory, and the database and Fineract configuration files alongside each backup set. Without these, a restore may fail on a version mismatch or attach to the wrong tenant layout. Include the global configuration values that affect restore behavior, and keep the secrets out of the record by referencing where they are held. The step is done when a backup manifest is generated automatically with each run and a reviewer can read the Fineract and PostgreSQL versions from it without access to the live system.
Run a first restore into an isolated environment
Restore the latest base backup plus archived WAL into an isolated environment that has no route to live payment, notification or event systems. Start Fineract against the restored tenants database and at least one tenant schema, then compare row counts for key tables such as clients, loan accounts and savings accounts against the source at the recovery point. Also verify loan balances for a sample of accounts, including loans with recent repayments and accrued interest, and check that the Close of Business state is consistent. The step is done when counts match, the sampled balances agree, and the results are signed off by the business owner as well as the technical owner.
Repeat restore tests on a defined schedule
Make restore testing a recurring control rather than a one-time project. Repeat the isolated restore on a schedule your risk owners approve, and each time check that the archive chain is complete, the manifest matches the restored versions, and the row-count and loan-balance checks pass. Record recovery time observed in each test so that recovery objectives are based on measured results. Confirm the schedule and the recovery objectives with your business continuity owner before go-live. The step is done when the test results are stored with the backup records and any failed check opens a tracked fix.
Protecting backup copies of core banking data
A backup of a Fineract database holds the same client, loan and ledger data as production, so it needs the same protection. The controls below cover who can read backups, how they are encrypted, who can restore them and how restores are recorded. Check each one against your own key management, identity and retention policies before go-live.
Encrypt backups at rest and in transit
Every dump, base backup and archived WAL segment should be encrypted before it lands on storage you do not fully control, and the transfer path from the database host to that storage should use TLS. Fineract's own HTTPS settings do not cover backup traffic, so the backup tool, storage client and key service each need their own configuration. Confirm where encryption keys live, who can rotate them, and whether an old backup can still be decrypted after a rotation.
Separate backup and restore credentials
The account that writes backups should not be able to read the live tenant data, and the account that restores should not be able to delete backups. Use distinct PostgreSQL roles for backup, restore and application access, and grant each only the privileges its job needs. Check that the role used by the backup job cannot alter the schemas it copies.
Require SCRAM and strong authentication
PostgreSQL 18 deprecated MD5 password authentication in favor of SCRAM, so backup and restore roles should be created with SCRAM-hashed passwords and scram-sha-256 set in pg_hba.conf. Where your environment supports it, consider certificate or OAuth 2.0 authentication for automated jobs so no long-lived password sits in a job definition. Confirm the exact method your PostgreSQL version and hosting platform support.
Restrict access to tenant secrets and tenants database
The tenants database holds the connection details for every tenant schema, so a copy of it reveals where each tenant's data lives and how to reach it. Limit read access to that database and its backups to the platform team, keep tenant database credentials in a secrets manager rather than in dumps, and exclude secret values from restore output and logs. Review who holds these grants each quarter and after any staff change.
Immutability and retention locks
Backups that an administrator can silently delete do not protect against ransomware or an insider who alters history. Store copies in object storage or a backup platform that supports write-once or retention locks, and set retention periods with your compliance owner, not the infrastructure team alone. Test that a locked backup cannot be removed with ordinary administrator credentials before relying on the lock.
Log every restore action
A restore overwrites or replaces live banking data, so each restore should have a recorded requester, approver, reason, source backup identifier and target environment. Capture the restore commands, timestamps and results in a central log that the backup administrators cannot edit. Keep these records with the restore test evidence so auditors can trace how any recovery was authorized and performed.
Setting recovery point and recovery time objectives for a core banking system
Set the recovery point objective (RPO) and recovery time objective (RTO) for Fineract before you choose a backup schedule or tool, because both numbers decide the design. The RPO is the most transactions the institution can afford to lose, measured as time. For a PostgreSQL-backed Fineract deployment, that maps directly to how often WAL segments are archived under continuous archiving, and to how often dumps are taken if you rely on them alone. A dump-only design can lose everything since the last dump, so a tight RPO normally requires archiving with point-in-time recovery. Confirm with the business owner whether the RPO applies to the tenants database, each tenant schema, or both, because a restore that brings back one tenant at an older point creates reconciliation work across the others.
The RTO is the longest acceptable outage from declared incident to service restored and verified. It cannot be estimated from backup tooling alone. It depends on how long a restore of your largest tenant takes on your hardware, how long replaying WAL takes to reach the target time, and how long the application needs to start and pass health checks against the restored database. Close of Business is a further dependency: if the restore point falls mid-cycle, the Fineract batch and its business date state must be checked before users return, which can add time that a plain database restore does not show. Record a measured restore duration from a rehearsal, including the COB check, and compare it with the RTO before go-live.
Targets are set by the institution and its regulator, and by any contractual commitments to customers and payment partners. DeployOpen does not supply RPO or RTO figures and will not present them as recommendations. Before design starts, write down the figures your regulator, board-approved resilience policy and service contracts require, the scope each figure covers, and who approves changes to them. Then confirm each figure with the accountable executive and your compliance function. Those confirmed numbers become the acceptance criteria for the restore tests described elsewhere on this page.
Limits to confirm in your environment before relying on backups
Backups for a core banking database only protect you if their limits are known. The cards below cover where replication, failover, upgrades, running COB jobs, configuration and tooling leave gaps that a dump or archive does not close. Each one names a check to run in your own environment or to confirm with the vendor before go-live.
Replication does not replace backups
A hot standby or read replica copies changes made to the primary, including a bad delete or an erroneous batch of postings. Replication therefore does not give you a copy of the state from before the mistake. Keep separate base backups and WAL archives, and confirm that a restore from them is tested on its own, outside the replication path. Check that the restore runbook does not assume the standby is still healthy.
Automatic failover needs external tools
PostgreSQL does not detect a failed primary and promote a standby by itself. If your design relies on automatic failover, the detection, promotion and client redirection come from tooling you select and operate. Confirm how Fineract instances reconnect after a promotion, how the tenants database is pointed at the new primary, and how a split brain is prevented. Test this with a planned failover before you rely on it.
Restores into newer majors need a path
A dump taken from one PostgreSQL major version does not automatically restore into another, and major upgrades can be done with pg_dumpall and restore, pg_upgrade, or logical replication. Each method has different rollback and downtime characteristics. Before you schedule a major upgrade, document which method you will use, rehearse a restore into the target version, and confirm that the Fineract release you run supports that PostgreSQL version.
COB backups may need validation
The Close of Business job can run for several hours on large deployments, and a backup taken during a run may capture loans that are locked or partly processed. Decide whether backups are scheduled outside the COB window, and check how the restored data behaves when a COB is resumed or rerun. Confirm the procedure with your Fineract support or vendor, and record the job run history alongside each backup so you can see what state it represents.
Configuration and secrets need backups
Global configuration, tenant connection settings, OAuth2 client details and TLS keys live partly outside the database, in environment variables, Kubernetes secrets, keystores or your secrets manager. A database restore alone cannot bring back a working deployment. Inventory every item that Fineract needs at startup, store its backup under your own access controls, and rehearse rebuilding a full environment from those copies.
MySQL and MariaDB tooling is out
Fineract recommends PostgreSQL, and MariaDB and MySQL are deprecated under FSIP-9. If an earlier environment or an acquired system still runs on those databases, the backup and restore procedures written for PostgreSQL will not apply to it. Confirm with the vendor which database platforms are supported for your Fineract release, and plan any migration before you rely on a restore process for a system outside that set.
Questions teams ask about Fineract backup and restore
How much effort does a Fineract backup design take, and what drives it?
The effort depends on how many tenants you run, how many PostgreSQL clusters hold their data, how long you need to recover to, and how many systems (document storage, event brokers, configuration) must be restored to the same point in time. A single tenant on one database with a nightly dump is a small design. Several tenants, read replicas, object storage for KYC documents and a recovery objective measured in minutes add retention rules, archive storage, monitoring of backup jobs and runbooks for each failure type. Ask any partner to list each component to be protected, the recovery objectives agreed with your risk function, and the deliverables in the written scope before you compare figures.
Can our internal team design and run Fineract backups without a partner?
Yes, if your team already runs PostgreSQL in production and has someone who can test a restore end to end. The skills needed are PostgreSQL backup tooling, archive and retention management, secrets handling for database credentials, and the ability to restore the tenants database and every tenant schema consistently. Teams with little PostgreSQL operations experience usually need outside help for the initial design and the first restore exercises, then run the routine themselves. Confirm the skills in your team against the design before deciding, and check the platform documentation for the Fineract side of the work.
What does the institution need to provide for a backup engagement?
The work needs decisions and access from your side. You must set recovery time and recovery point objectives per system, confirm which data classes and regulatory retention periods apply, and name owners for backup approval and restore sign-off. Engineering needs access to the PostgreSQL clusters, the tenants database, the storage account or data center where archives will live, and the Fineract deployment configuration. You also need a change window for restore tests in a non-production environment that mirrors production. Missing decisions on retention and sign-off are the most common reasons a design stalls.
How long does restore testing take, and what sets that time?
Restore time scales with database size, the number of tenant schemas, the speed of the archive storage and network, and the number of steps in the runbook, including replaying archived write-ahead logs to a target time. Verification after the restore, such as confirming Liquibase migration state, checking that each tenant resolves through the tenants database and reconciling a sample of balances, adds time that is often underestimated. Ask for the measured restore duration from a test on data of comparable size, not an estimate, and ask whether the test covers a full restore, a single tenant restore and a point-in-time restore.
Do PostgreSQL replicas count as backups for Fineract data?
No. Replicas protect availability when a server fails, but they copy mistakes as well as data. A dropped tenant schema, a bad batch update or a faulty migration reaches every replica within moments, so a separate backup copy is still required. PostgreSQL hot standbys serve read-only queries and can run synchronous or asynchronous replication, and PostgreSQL does not provide automatic failover on its own. Keep replicas for high availability, keep independent, versioned backups for recovery, and test both paths separately.
How does point-in-time recovery differ from a plain database dump?
A dump captures the database as it was when the dump ran, so anything written after that moment is lost. Point-in-time recovery restores a base backup and then replays archived write-ahead log files up to a chosen time, which narrows the gap to the failure. Continuous archiving needs the archive command, retention of base backups and log segments, and monitoring so that a broken archive is noticed before it is needed. For a core banking ledger, the usual pattern is base backups with continuous archiving for recovery, and periodic logical dumps as an additional, separately tested copy. Confirm the archive settings against the PostgreSQL continuous archiving documentation.
How do backup plans change before a PostgreSQL or Fineract upgrade?
Before any upgrade, take a fresh, verified backup and keep the previous one until the upgrade is accepted. The PostgreSQL upgrade method changes the plan: a pg_dumpall and restore needs a full copy and downtime, while pg_upgrade and logical replication change the rollback path. Each PostgreSQL major version has a support end date, so schedule upgrades before a version leaves support. Fineract upgrades also run database migrations, so the restore procedure for a failed upgrade must match the release you are moving from. Rehearse the rollback in a non-production environment with a restored copy before the production window.
How DeployOpen scopes and tests Fineract backup and restore
DeployOpen plans, builds, tests and documents backup and restore for Fineract inside infrastructure you control, including the tenants database and every tenant schema. Work starts from written recovery objectives and ends with restore tests your operations team can repeat.
How we scope
- Inventory every Fineract database, including the tenants database and each tenant schema, with its owner and hosting location.
- Agree recovery point and recovery time objectives in writing with your risk, finance and operations owners before design starts.
- Define the written scope, deliverables and timeline before work begins, with ongoing testing available as a retainer.
How we build
- Design the backup method (logical dumps, continuous archiving or both) around the objectives and the PostgreSQL version in use.
- Configure archive storage, retention, encryption and access controls in your environment, with separate credentials for backup and restore.
- Run a full restore into an isolated environment and check tenant data, schema versions and transaction counts against the source.
How we hand over
- Document the backup schedule, restore runbook and tenant-by-tenant recovery steps so your team can execute them without us.
- Provide restore test records showing what was restored, when, by whom and what was verified.
- Walk your operations and security staff through alerting for failed backups and archive gaps before handover is signed off.
How we support
- Repeat restore tests on a schedule you approve, especially after Fineract or PostgreSQL upgrades that change the database layout.
- Review backup coverage when tenants are added, schemas change or hosting moves to a new cloud account or data center.
- Support recovery exercises and incident restores under a retainer, with scope agreed in writing in advance.
