> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Reporter to Midaz

> Connect Reporter to Midaz through a named data source, protect the source database with least-privilege credentials, and verify the connection end to end.

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:

```text theme={null}
{{ midaz_onboarding.account.name }}
```

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.

<Warning>
  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.
</Warning>

## 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:

```env theme={null}
DATASOURCE_EXTERNAL_DB_SCHEMAS=sales,inventory,reporting
```

See [Configure external data sources](/en/reporter/using-reporter#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](/en/reference/reporter/list-data-sources) and confirm that the expected `configName` appears.
2. Copy the data source ID from the response.
3. [Retrieve the data source](/en/reference/reporter/retrieve-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

***

* [Create your first report](/en/reporter/reporter-quick-start)
* [Build templates and filters](/en/reporter/using-reporter)
* [See Reporter in a complete core banking architecture](/en/building-a-complete-core-banking)