Skip to main content
Reporter reads Midaz data through a named data source. A report template references that name, and Reporter turns its placeholders and filters into queries against the source database. For example, a template can reference an account from the midaz_onboarding data source:
Reporter builds SELECT queries for PostgreSQL sources and Find operations for MongoDB sources. It then renders the returned data through the template. Reporter does not write back to the source databases or persist report results in Midaz.

​
Before you start

You need:
  • Network access from Reporter to the Midaz database.
  • A database user with read-only permissions.
  • Preferably, a read replica so report workloads do not compete with ledger workloads. The reference setup uses the host midaz-postgres-replica as an example.
  • The database, schemas, and tables that your templates need.
Reporter generates read operations, but this behavior does not enforce database permissions. Use read-only database credentials. Do not give Reporter a user that can insert, update, delete, or change schemas.

​
Choose who manages the connection

Your deployment model determines who configures the data source:
  • Managed (Lerian-hosted): the connection to your Lerian product data is set up during onboarding. Confirm the data source name and availability with your Lerian contact before you build templates.
  • Self-hosted: your operator configures the connection at deployment time and owns its network access, credentials, certificates, and database permissions.
In both models, report authors reference the configured data source by its configName.

​
Configure a named data source

In a self-hosted deployment, define the connection with DATASOURCE_<NAME>_* environment variables. Set DATASOURCE_<NAME>_CONFIG_NAME to the stable name that templates and filters will use. For example, if the configName is midaz_onboarding, templates reference midaz_onboarding even if the database host or credentials change later. For PostgreSQL sources that expose more than one schema, derive the schema variable from the configName. A configName of external_db uses:
See Configure external data sources for the connection variables and complete examples.

​
Protect the Midaz database

Use a dedicated database role that can connect and select only the required tables and schemas. Point Reporter to a read replica when your topology supports one. This keeps report queries away from the primary database, but the replica is not a substitute for read-only credentials: apply both controls. Rotate the credential through your normal secret-management process. Keep the configName stable so existing templates continue to resolve the same data source.

​
Verify the connection

  1. List data sources and confirm that the expected configName appears.
  2. Copy the data source ID from the response.
  3. Retrieve the data source and confirm that Reporter discovers the expected schemas, tables, and fields.
  4. Create a small template that references one known field, then generate a report to verify the complete query and rendering path.
The connection is ready when the named source is available, its discovered structure is correct, and the test report returns the expected value.

​
Troubleshooting

​
The data source is unavailable

Check network routing, DNS, TLS settings, credentials, database permissions, and replica health. During template validation, Reporter can return a DATA_SOURCE_UNAVAILABLE warning instead of blocking template creation. Fix the connection before relying on the report output.

​
The source name is ambiguous

Use one descriptive configName per database role, such as midaz_onboarding and midaz_transaction. Avoid generic names such as database or postgres, especially when different sources contain tables with the same names. Update the template to reference the intended source explicitly.

​
Next steps