Apache Fineract reporting with Superset or Metabase

Reporting on Apache Fineract data without loading the write database

A bank or lender that wants portfolio, PAR and ledger dashboards should not point a BI tool at the live write instance of Apache Fineract. The Fineract documentation describes a multi-instance layout with one write instance, one batch instance and multiple read instances, and the read instances run on read replicas of the Fineract database. That separation keeps analytical queries away from the transactions, Close of Business processing and Liquibase migrations that the write side must complete. The reporting pattern follows from it: Superset or Metabase connects to a PostgreSQL read replica, and dashboards draw from reporting views defined on that replica rather than from the raw Fineract tables. Confirm with your Fineract version which tables and columns the views will depend on, because the schema changes between releases and each change will break the views until they are updated.

Both tools can run against that replica, so the choice between them is a governance and licensing decision as much as a technical one. Apache Superset is Apache-2.0 licensed with no paid edition, and its metadata database, caching layer and Celery workers are components your team operates. Metabase's open source edition is AGPL, and the features that matter for branch-level access, including row and column level permissions, SSO and multi-tenant data segregation, are included only in its Pro and Enterprise plans according to its pricing page. Ask both vendors to confirm current plan contents before you decide, and map the answer to your requirement that a branch manager sees only their own loans and arrears.

Plan the row-level access model before building the first dashboard, because it determines where filtering happens. Options include database-level roles on the replica, filters in the view definitions keyed to the Fineract office hierarchy, and the tool's own permission model. Test each option with a branch user account and a known set of loans, and confirm that the PAR and ledger figures match the write instance at the same business date. Document the replica lag you accept, since reports will reflect the replica's position rather than the live write database. Also plan the replica's backup and failover separately, since PostgreSQL does not detect a failed primary or promote a standby on its own.

What you need in place before building dashboards

Dashboards on Fineract data depend on several components that must exist before any BI tool is installed. The cards below cover the database, the Fineract release, the replica and its owner, network and TLS, and the BI metadata store, in the order a team should settle them.

PostgreSQL version and support window

Fineract recommends PostgreSQL, and the replica must run the same major version family your write database uses so that replication and restores stay predictable. PostgreSQL 14 is supported until November 12, 2026, while 15, 16, 17 and 18 have later end dates. Check the version against the support calendar before you choose it, because a replica built on an version nearing end of life adds an upgrade to your first quarter of operation.

Fineract 1.x release in use

Confirm which Fineract 1.x release runs your write instance, since the schema the views depend on changes between releases. Fineract releases quarterly and archives end-of-life releases, so the reporting layer should be written against a named release and retested after each upgrade. Fineract CN is archived and is not a valid base for new reporting work.

Instance types configured first

Set the write, batch and read instance types with environment variables before you attach the replica. Liquibase migrations run only on write instances, so a read instance that points at a replica must never be the one that migrates the schema. Verify that the reporting path reads only from instances declared as read.

Replica with a named owner

Assign one person or team to own the PostgreSQL read replica, including its lag, its disk, its restore tests and its failover runbook. Streaming replication keeps a standby serving read-only queries, but PostgreSQL does not detect primary failure or promote a standby on its own. Record who answers when replay lag grows, because dashboards will show stale numbers without an error.

Network paths and TLS

Document every connection from the BI tool to the replica, the metadata database and any connection pooler, and allow only those paths. Require TLS on each hop and reject unauthenticated access from the BI network. Fineract documents HTTPS-only operation through settings such as FINERACT_SERVER_SSL_ENABLED, and the database connections need the same discipline.

Metadata database for the BI tool

Superset and Metabase both store dashboards, users, roles and saved queries in their own application database, which is separate from the Fineract replica. Use PostgreSQL or MySQL for that store and back it up before every upgrade, since neither tool should keep metadata in a bundled SQLite or H2 file in production. Keep this database on a different host or schema from the Fineract replica so that BI writes never reach core data.

How to build the reporting path in order

This sequence moves from a read-only copy of the Fineract database to validated dashboards, so each layer is checked against the layer below before the next one is built. The result is a BI path that reports on portfolio, PAR and ledger data without touching the write instance.

Provision the read replica and lag monitoring
The platform team creates a PostgreSQL streaming replica of the Fineract database, using the hot standby model PostgreSQL documents for read-only queries, and places it on a network path that the BI tier can reach. Confirm that replication lag is measured and alerted on, because reports built on a stale copy will disagree with the Fineract API. Close the step by comparing a known client count on the primary and the replica after a write, and by confirming that the lag alert fires in a test. Ask the team that operates PostgreSQL to confirm how replica failover will work, since PostgreSQL does not detect primary failure on its own.
Create a read-only reporting role
The database administrator creates a dedicated login role for reporting, grants it connect and select rights only on the schemas and views the reports need, and sets default transaction mode to read-only. Credentials should use SCRAM password authentication, and the role should not own any objects or have write access to the Fineract schema. Connections should use TLS. The step closes when a test session can select from a permitted table and receives a permission error on an insert or update attempt against the same replica.
Build schema views for portfolio, PAR and ledger
The data engineer writes reporting views over the replica for loan portfolio balances, days-past-due buckets for portfolio at risk, and general ledger journal totals by account and office. Each view should document its grain, its source tables, how it handles reversed or adjusted entries, and which Fineract business date it reflects. Keep the view definitions in version control and review them with the finance team, who own the definitions of PAR and balances. The step closes when the portfolio total from a view matches the outstanding balance reported by the Fineract API for the same date and office, and when the ledger view balances to zero per journal.
Deploy Superset or Metabase with production metadata storage
The platform team deploys Apache Superset or Metabase on infrastructure the organization controls. Superset needs a user-specified SECRET_KEY to start, and the team should plan the metadata database instead of the SQLite default, which the architecture documentation does not recommend for production. Metabase should move its embedded H2 application database to PostgreSQL before production use. Store the secret key or encryption key in the organization's secrets store and document the rotation procedure. The step closes when the tool starts cleanly, the metadata database is backed up, and a restart preserves saved users and dashboards.
Connect the replica as a data source
An administrator registers the read replica in the BI tool using the read-only role and limits the connection pool so reporting queries cannot exhaust connections on the replica. Set query timeouts and decide whether caching or background refresh is used, which for Superset requires the caching layer and worker components. Confirm that the tool lists only the reporting views and not the underlying Fineract tables. The step closes when a sample query from the tool returns the same row count as the same query run directly against the replica.
Apply tenant separation and branch row-level access
The team maps each Fineract tenant to its own reporting view or schema filter, and maps branch or office staff to the rows they may see. Superset supports role mapping from OAuth or LDAP groups, while Metabase row and column level permissions and multi-tenant segregation require its Pro or Enterprise plans, according to its pricing page. Confirm the plan and licensing before design. The step closes when a test user from one branch cannot see another branch's loans, and a test user from one tenant cannot see another tenant's data, both checked in the BI tool itself.
Build and validate dashboards against the API
The reporting team builds the portfolio, PAR and ledger dashboards on the validated views, with filters for office, product and business date. Before release, reconcile each headline figure against the Fineract API or a Fineract report for the same date, and record any differences with their cause. Share the reconciled results with finance and risk owners for sign-off. The step closes when every headline figure has a reconciliation record and the owners have approved the dashboards for use, with a documented process for re-running the reconciliation after each Fineract upgrade.

Choosing between Apache Superset and Metabase for this build

Both tools are open source, but their licenses and commercial offers differ, and that difference decides what you pay for later features. Apache Superset is an Apache Software Foundation project released under the Apache License 2.0, and the project has no paid edition. Metabase publishes its open source edition under the AGPL and its commercial editions under the Metabase Commercial Software License, so the features you need determine which code and plan you run.

Superset license: Apache-2.0 applies to the whole project, with no separately licensed commercial tier to buy.
Metabase open source: The AGPL edition is free, but it omits several access controls covered in the next tab.
Metabase paid plans: Starter, Pro and Enterprise are listed on the pricing page, with per-user charges beyond the included seats.
Enterprise pricing: Enterprise is priced by quote, starting at $20,000 per year according to the pricing page.
Licensing review: Have counsel confirm how the AGPL and the commercial license apply to your internal use and any embedding.

Figures come from Metabase's pricing page at the time of research. Confirm current plans, seat rules and license terms with each vendor before you budget.

Branch-level reporting depends on row-level access, tenant separation and single sign-on, and these features sit in different places in each tool. Metabase's pricing page places SSO, row and column level permissions, and multi-tenant data segregation in the Pro and Enterprise plans, so an open source Metabase deployment cannot enforce branch restrictions through its own permissions. Superset is built on Flask-AppBuilder and maps OAuth or LDAP groups to roles through AUTH_ROLES_MAPPING, which means access is shaped by roles and the datasets behind them.

Metabase SSO: SAML, JWT and OIDC setups for providers such as Keycloak, Okta and Entra ID require Pro or Enterprise.
Metabase LDAP: Basic LDAP and Google sign-in are available on Open Source and Starter, while advanced group and attribute sync and SCIM need Pro or Enterprise.
Superset OAuth and LDAP: Superset supports OAuth2 providers, custom OAuth2 servers using the code flow, and LDAP, with group-to-role mapping in AUTH_ROLES_MAPPING.
Row-level design: In Superset, plan row restrictions in the database views or role definitions that the branch roles query, since the view layer is where the branch filter must hold.
Confirm: Test each branch role against a copy of the replica to verify that no other branch's rows are returned.

Before choosing, map your identity provider and branch access rules to the features each plan includes, and confirm those features in the current documentation.

Upgrade cadence and the steps each project requires affect how much operating effort the reporting layer will recur. Metabase publishes version support with LTS releases supported for 14 months and non-LTS releases usually reaching end of life after two months. Superset's upgrade guidance asks you to back up the metadata database, run superset db upgrade and superset init, test in staging first, and check UPDATING.md for breaking changes.

Metabase cadence: Choose an LTS line if you want a longer support window, and note the end-of-life date of each release you run.
Metabase migrations: Application database migrations run automatically at startup, so the backup must be taken first.
Superset steps: Run superset db upgrade and superset init after each version change, and review UPDATING.md for breaking changes.
Secret keys: Superset requires a user-specified SECRET_KEY and supports rotation with PREVIOUS_SECRET_KEY, which must be handled in every upgrade.
Staging: Test each upgrade against a copy of the replica and the metadata database before production.

Before you commit, ask each vendor for its current support calendar, and budget upgrade time for the release line you choose.

Mapping Fineract tables and branch attributes to reporting views

This table traces each reporting concept to the Fineract source it comes from, the view that exposes it, the rule that filters it and the owner who approves the definition. Rows marked as needing verification depend on your Fineract schema, configuration and products, so confirm them against your own database before any dashboard goes live. Use the table as a sign-off checklist, not as a finished schema map.

Reporting concept	Fineract source to verify	View and access rule	Sign-off owner
Portfolio outstanding balance	Loan account balance fields and loan transaction records on the read replica (verify column names and transaction types in your schema)	View reporting.v_portfolio_balance, filtered by office rule for each branch role	Head of credit risk
Portfolio at risk (PAR) buckets	Loan arrears and overdue fields derived from the repayment schedule (verify how your products define days past due)	View reporting.v_par_buckets, restricted to branch and regional roles through row-level policy	Chief risk officer
Client and group attributes	Client records, KYC document references and group membership (verify which KYC fields your team has enabled)	View reporting.v_client_profile, with personal identifiers masked for analyst roles	Data protection officer
General ledger balances	Accounting journal entries and GL account mappings from the accounting module (verify accounting mode and closure periods)	View reporting.v_gl_balances, available to finance roles only	Financial controller
Office and branch hierarchy	Office records and parent office relationships in the tenant schema (verify the hierarchy depth used by your network)	View reporting.v_office_tree, used as the basis for row-level access checks	Head of branch operations
Tenant identifier	Tenant records in the tenants database, which map each tenant to its own connection (verify whether you run one tenant or several)	Dashboards filtered to one tenant per data source, with no cross-tenant joins	Platform owner
Business date and end-of-day status	Business date and Close of Business job status (verify that the replica reflects the last completed job)	View reporting.v_business_date, shown on every dashboard as a data freshness label	Operations manager
Staff-to-branch assignment	Staff and office assignment records (verify whether users are linked to offices in your configuration)	Mapping table reporting.map_user_office, which drives the row-level policy and is changed only through an approved request	Security lead

Securing the replica, the BI tool and branch access

The reporting stack holds a copy of every loan, savings and ledger record, so it needs the same access discipline as the write database. The cards below cover the database layer, the BI tool's own configuration and the branch-level rules that decide who sees which portfolio. Work through them in order, because the replica role and tenant boundary constrain everything built on top.

Read-only database role on the replica

Create a dedicated PostgreSQL role for the BI tool that has CONNECT and SELECT on the reporting schema views only, with no rights on the Fineract base tables, no INSERT, UPDATE or DELETE, and no ability to create objects. Keep the role separate from the Fineract application user and from any migration or batch account. Test the grant by attempting a write from the BI connection and confirming it fails. Ask the team who owns the password rotation for this role.

TLS and PostgreSQL authentication methods

Require TLS on every connection from the BI tool to the replica and reject plain connections in pg_hba.conf. Choose an authentication method the PostgreSQL server supports and your security team accepts, such as SCRAM password authentication, certificate authentication or an OAuth 2.0 method if your PostgreSQL version and identity provider support it. MD5 password authentication is deprecated in favor of SCRAM, so check it is not in use. Confirm the BI tool's driver supports the chosen method before committing to it.

Separating tenant data in views

Fineract is multi-tenant, with each tenant's data held in its own database. Decide whether each reporting database serves one tenant or whether a single replica holds several, and document the answer. If several tenants share one reporting database, every view must filter by tenant and the BI connection must not be able to query another tenant's schema. Test with two tenant identifiers before go-live, because a missing filter in one view is a cross-tenant data exposure.

Branch-level row access in the BI tool

Branch restrictions are usually enforced in the BI tool, not in the database, so the mapping must be designed deliberately. Metabase documents row and column level permissions, multi-tenant data segregation and usage auditing as Pro and Enterprise features, and Superset applies data access through its own role and dataset rules. Whichever tool you choose, confirm in a test that a branch manager's query returns only that branch's loans, and that users cannot bypass the filter with a custom query. Record which role is trusted to see all branches.

SECRET_KEY handling and rotation in Superset

Superset refuses to start without a user-specified SECRET_KEY, and that key signs session data and encrypts stored database credentials. Generate a long random value, store it in your secrets manager, and never commit it to the image or configuration repository. To rotate it, set PREVIOUS_SECRET_KEY alongside the new key, then follow the rotation steps in the configuration docs. Plan the rotation in a window that includes a metadata database backup, because a wrong rotation can lock users out or break saved connections.

SSO group mapping to BI roles

Map identity provider groups to BI roles in one place so that branch access follows HR changes automatically. Superset uses AUTH_ROLES_MAPPING for OAuth or LDAP groups. In Metabase, JWT, OIDC, SAML and advanced LDAP group sync require the Pro or Enterprise plan, while Open Source and Starter support Google sign-in and LDAP only. Decide who approves a new group mapping and how a departing employee's access is removed on the same day their directory account is disabled.

Audit of dashboard and query access

Decide what must be logged before go-live: logins, dashboard views, exported data, changed datasets and failed authentication. Metabase lists usage analytics and auditing as a Pro and Enterprise feature, so confirm it is in the plan you buy. For Superset and the replica, enable PostgreSQL connection and statement logging for the BI role and send logs to your central store. Review the logs on a fixed schedule, and confirm retention with your compliance lead rather than assuming a default.

Common reporting failures and how to fix them

This table lists the failures teams most often hit when BI tools sit on Fineract data, with the cause and the fix for each. Use it as a checklist during build and as a triage guide after go-live. The main takeaway is that most failures trace back to three things: reads reaching the write path, views that assume a fixed schema, and access rules applied in the BI tool rather than the database.

Failure	Likely cause	Fix
Stale dashboards from replica lag	The read replica falls behind the write instance under heavy write load, so figures lag the live portfolio	Monitor replication lag as a dashboard metric, set an agreed freshness expectation with report owners, and show the data-as-of time on every dashboard
Reports hitting the primary by mistake	A connection string in Superset or Metabase points at the write database, often copied from a Fineract environment file	Create a read-only role on the replica only, restrict the write host from the BI network, and audit data source settings after each change
Views double counting after schema changes	Views join transaction and journal tables without filters, and a Fineract upgrade adds rows or columns that change the join result	Pin view definitions to tested columns, add a regression query with known totals, and rerun reconciliation to the ledger after every platform upgrade
Metadata database on SQLite	The Quickstart or PyPI default stores Superset or Metabase settings in a local file, which is not suited to production	Move the metadata or application database to PostgreSQL (or MySQL for Superset) before loading users, and back it up before any upgrade
Missing row-level rules for a branch	Access is granted at dashboard level only, so a branch user can see other branches' rows through a shared dataset	Define row-level rules on the dataset or database role, test them with a non-admin account per branch, and confirm the feature is included in your Metabase plan
Breakage after a Superset or Metabase upgrade	Version changes alter configuration, migrations or chart behavior, and the upgrade was run without a backup or staging test	Back up the metadata database, test in staging, read the release notes and UPDATING.md for Superset, and upgrade one release at a time as the upgrade docs advise

Questions buyers ask before building Fineract reporting

What drives the cost of building Fineract reporting?

The main cost drivers are the number of reporting views, how many tenants and branches must be separated, how complex the row-level access rules are, how the read replica and BI hosting are sized, and which SSO tier the BI tool needs. Each view for portfolio, PAR or ledger reporting needs definition, testing and sign-off, so the count matters more than the tool choice. Ask for a quote that lists each view, each tenant boundary, each access rule, the replica and BI hosting, and the SSO tier separately. Hosting and licensing are recurring costs, while schema design and testing are one-time. Metabase's published pricing shows that SSO, row-level permissions and multi-tenant segregation are limited to its Pro and Enterprise plans, so that tier choice affects cost directly.

How long does a Fineract reporting build take?

Duration depends on the number of views, how many PAR and ledger definitions must be agreed with the business, how many tenants share the instance, and how much the access model has to be tested. No duration figure is given here because it depends on the scope agreed in writing. Definition workshops often take longer than the technical build, since PAR and ledger logic must be signed off before dashboards are trusted. Confirm with the vendor and your own environment whether a read replica already exists, because creating one adds infrastructure work before any BI tool is connected.

What must our team provide for a reporting build?

Your team must name schema owners who can explain Fineract's tables and business meaning, and approvers who can sign off on PAR and ledger definitions before dashboards go live. You also need access to a staging environment, a read replica or a place to create one, and identity administrators for SSO and group mapping. Finance owns the ledger mapping decisions, risk owns the PAR bucket definitions, and branch managers or operations leads define row-level access rules. Without these named people, reports tend to disagree with each other and the build stalls waiting for answers.

Can our internal team build Fineract reporting without a partner?

Yes, an internal team with PostgreSQL, Fineract data model and BI experience can build it, provided it has time and the definition owners are available. The harder parts are not the SQL but the agreed definitions of PAR, portfolio and ledger balances, and testing row-level access across tenants. Ask your team to confirm it can operate a replica, rotate the BI secret key, and run upgrades with a tested backup. Teams that lack Fineract experience often need the most time on the data model. A partner can plan the build as a fixed-scope engagement with written deliverables, which some organizations prefer for this kind of work.

Are reports built on Fineract data audit evidence?

No. A dashboard built on Fineract data is an operational reporting tool, not audit evidence, and it does not produce an audit report or attestation. Auditors need to trace figures to source records, confirm who had access, and see how definitions were approved and changed. DeployOpen prepares systems, controls and evidence for compliance assessments, but independent auditors and certification bodies issue the opinions. Ask your auditors early which evidence they will accept, such as documented query definitions, change records and access logs.

Why use a read replica instead of the write database for BI?

The Fineract documentation recommends separating read load from the write instance by using read instances on database read replicas, which keeps heavy analytical queries away from the database that processes transactions. PostgreSQL supports hot standby servers that serve read-only queries, and both synchronous and asynchronous replication. Asynchronous replicas can lag behind the primary, so dashboards may show figures a little behind live data. Confirm the acceptable lag with your finance and risk owners before the first dashboard is approved.

What is the security risk of connecting a BI tool to Fineract?

The main risk is that a BI user sees data they should not, especially client records across branches or tenants. Use a dedicated read-only database role, row-level rules for branches, and a separate tenant boundary for each tenant. Superset requires a user-specified SECRET_KEY to start and supports rotating it with PREVIOUS_SECRET_KEY, so plan key storage from the outset. Test access rules with real user accounts from each branch before go-live.

How DeployOpen scopes and delivers Fineract reporting

DeployOpen plans, builds, documents and supports Superset or Metabase reporting on Fineract data inside infrastructure you control. The work starts from a written scope that sets which reports, which tenants and which reader roles are in play, and the read path is kept separate from the Fineract write instance.

How we scope

Written scope lists the portfolio, PAR and ledger reports, and the branch and tenant audiences each one serves.
Scope records the chosen BI tool, its licence tier and the access features that tier must include.
Scope confirms the PostgreSQL version, replica topology and network paths agreed with your platform team.

How we build

Read replica is configured and checked for replication lag before any dashboard queries it.
Reporting schemas and views are built on the replica, with reviewed definitions for each financial metric.
Row-level access for branches and tenants is tested with sample users before reports reach staff.

How we hand over

Handover includes view definitions, metric notes, dashboard inventory and the access model in writing.
Runbooks cover metadata database backup, Superset or Metabase upgrades and replica failover steps.
Your team receives walkthroughs and a test checklist so changes to views can be verified before release.

How we support

Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
Ongoing support, upgrades and continuous testing are available as a retainer after handover.
Ask any quote to separate one-time build effort from recurring support, licence and infrastructure costs.

Reporting on Apache Fineract data with Apache Superset or Metabase