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

# Conectar o Reporter ao Midaz

> Conecte o Reporter ao Midaz por meio de uma fonte de dados nomeada, proteja o banco de dados de origem com credenciais de privilégio mínimo e verifique a conexão de ponta a ponta.

O Reporter lê dados do Midaz por meio de uma **fonte de dados** nomeada. Um template de relatório referencia esse nome, e o Reporter transforma seus placeholders e filtros em consultas ao banco de dados de origem.

Por exemplo, um template pode referenciar uma conta a partir da fonte de dados `midaz_onboarding`:

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

O Reporter monta consultas `SELECT` para fontes PostgreSQL e operações `Find` para fontes MongoDB. Em seguida, ele renderiza os dados retornados por meio do template. O Reporter não grava de volta nos bancos de dados de origem nem persiste resultados de relatórios no Midaz.

## Antes de começar

***

Você precisa de:

* Acesso de rede do Reporter ao banco de dados do Midaz.
* Um usuário de banco de dados com permissões somente leitura.
* Preferencialmente, uma réplica de leitura para que as cargas de trabalho de relatórios não concorram com as cargas de trabalho do ledger. A configuração de referência usa o host `midaz-postgres-replica` como exemplo.
* O banco de dados, os schemas e as tabelas que seus templates precisam.

<Warning>
  O Reporter gera operações de leitura, mas esse comportamento não impõe permissões de banco de dados. Use credenciais de banco de dados somente leitura. Não dê ao Reporter um usuário que possa inserir, atualizar, excluir ou alterar schemas.
</Warning>

## Escolha quem gerencia a conexão

***

Seu modelo de deploy determina quem configura a fonte de dados:

* **Gerenciado (hospedado pela Lerian):** o onboarding configura a conexão com os dados do seu produto Lerian. Confirme o nome e a disponibilidade da fonte de dados com seu contato na Lerian antes de criar templates.
* **Self-hosted, single-tenant:** seu operador pode popular a conexão na inicialização com variáveis `DATASOURCE_<NAME>_*` e é responsável pelo acesso de rede, credenciais, certificados e permissões de banco de dados.
* **Self-hosted, multi-tenant:** seu operador cria e gerencia as fontes de dados de cada tenant por meio da API do Reporter. A população de `DATASOURCE_*` na inicialização não é o caminho de configuração multi-tenant.

Em todos os modelos, os autores de relatórios referenciam a fonte de dados configurada pelo seu `configName`.

## Configure uma fonte de dados nomeada

***

Em um deploy self-hosted single-tenant, defina a conexão com variáveis de ambiente `DATASOURCE_<NAME>_*`. Defina `DATASOURCE_<NAME>_CONFIG_NAME` como o nome estável que os templates e filtros usarão. Em deploys multi-tenant, crie a fonte de dados pela API do Reporter.

Por exemplo, se o `configName` for `midaz_onboarding`, os templates referenciam `midaz_onboarding` mesmo que o host do banco de dados ou as credenciais mudem depois.

Para fontes PostgreSQL que expõem mais de um schema, derive a variável de schema a partir do `configName`. Um `configName` de `external_db` usa:

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

Veja [Configurar fontes de dados externas](/pt/products/reporter/using-reporter#configure-external-data-sources) para as variáveis de conexão e exemplos completos.

## Proteja o banco de dados do Midaz

***

Use uma role de banco de dados dedicada que possa conectar e selecionar apenas as tabelas e schemas necessários. Aponte o Reporter para uma réplica de leitura quando sua topologia oferecer suporte a uma. Isso mantém as consultas de relatórios longe do banco de dados primário, mas a réplica não substitui credenciais somente leitura: aplique os dois controles.

Rotacione a credencial pelo seu processo normal de gestão de segredos. Mantenha o `configName` estável para que os templates existentes continuem resolvendo para a mesma fonte de dados.

## Verifique a conexão

***

1. [Listar fontes de dados](/pt/reference/products/reporter/list-data-sources) e confirme que o `configName` esperado aparece.
2. Copie o ID da fonte de dados a partir da resposta.
3. [Obter a fonte de dados](/pt/reference/products/reporter/retrieve-data-source) e confirme que o Reporter descobre os schemas, tabelas e campos esperados.
4. Crie um template pequeno que referencie um campo conhecido e, em seguida, gere um relatório para verificar o caminho completo de consulta e renderização.

A conexão está pronta quando a fonte nomeada está disponível, sua estrutura descoberta está correta e o relatório de teste retorna o valor esperado.

## Solução de problemas

***

### A fonte de dados está indisponível

Verifique o roteamento de rede, DNS, configurações de TLS, credenciais, permissões de banco de dados e a saúde da réplica. Durante a validação do template, o Reporter pode retornar um aviso `DATA_SOURCE_UNAVAILABLE` em vez de bloquear a criação do template. Corrija a conexão antes de confiar na saída do relatório.

### O nome da fonte é ambíguo

Use um `configName` descritivo por role de banco de dados, como `midaz_onboarding` e `midaz_transaction`. Evite nomes genéricos como `database` ou `postgres`, especialmente quando fontes diferentes contêm tabelas com os mesmos nomes. Atualize o template para referenciar explicitamente a fonte pretendida.

## Próximos passos

***

* [Crie seu primeiro relatório](/pt/products/reporter/reporter-quick-start)
* [Crie templates e filtros](/pt/products/reporter/using-reporter)
* [Veja o Reporter em uma arquitetura completa de core banking](/pt/products/building-a-complete-core-banking)