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

# Referência de configuração

> Consulte todos os parâmetros Helm do serviço Ledger — bancos por módulo, secrets externos e flags de deploy do Midaz no Kubernetes.

## Referência de configuração do serviço Ledger

***

O serviço Ledger usa configurações de banco de dados específicas por módulo:

<CodeGroup>
  ```yaml values.yaml expandable theme={null}
  ledger:
    enabled: true
    name: "ledger"
    replicaCount: 1

    image:
      repository: lerianstudio/midaz-ledger
      tag: ""  # Defaults to Chart.AppVersion
      pullPolicy: IfNotPresent

    configmap:
      # App Configuration
      ENV_NAME: "production"
      LOG_LEVEL: "debug"
      SERVER_PORT: "3002"
      SERVER_ADDRESS: ":3002"

      # Auth Configuration
      PLUGIN_AUTH_ENABLED: "false"
      PLUGIN_AUTH_HOST: ""

      # Accounting Configuration
      # Managed via Ledger Settings API — see PATCH /v1/organizations/{org_id}/ledgers/{ledger_id}/settings
      # Request body: {"accounting": {"validateRoutes": true, "validateAccountType": true}}

      # PostgreSQL - Onboarding Module
      DB_ONBOARDING_HOST: "midaz-postgresql-primary.midaz.svc.cluster.local."
      DB_ONBOARDING_USER: "midaz"
      DB_ONBOARDING_NAME: "onboarding"
      DB_ONBOARDING_PORT: "5432"
      DB_ONBOARDING_SSLMODE: "disable"
      DB_ONBOARDING_REPLICA_HOST: "midaz-postgresql-replication.midaz.svc.cluster.local."

      # PostgreSQL - Transaction Module
      DB_TRANSACTION_HOST: "midaz-postgresql-primary.midaz.svc.cluster.local."
      DB_TRANSACTION_USER: "midaz"
      DB_TRANSACTION_NAME: "transaction"
      DB_TRANSACTION_PORT: "5432"
      DB_TRANSACTION_SSLMODE: "disable"
      DB_TRANSACTION_REPLICA_HOST: "midaz-postgresql-replication.midaz.svc.cluster.local."

      # MongoDB - Onboarding Module
      MONGO_ONBOARDING_HOST: "midaz-mongodb.midaz.svc.cluster.local."
      MONGO_ONBOARDING_NAME: "onboarding"
      MONGO_ONBOARDING_USER: "midaz"
      MONGO_ONBOARDING_PORT: "27017"

      # MongoDB - Transaction Module
      MONGO_TRANSACTION_HOST: "midaz-mongodb.midaz.svc.cluster.local."
      MONGO_TRANSACTION_NAME: "transaction"
      MONGO_TRANSACTION_USER: "midaz"
      MONGO_TRANSACTION_PORT: "27017"

      # Redis (shared)
      REDIS_HOST: "midaz-valkey-primary.midaz.svc.cluster.local.:6379"

      # RabbitMQ (shared)
      RABBITMQ_HOST: "midaz-rabbitmq.midaz.svc.cluster.local."
      # RABBITMQ_VHOST: "/"

      # Database Connection Pools
      # DB_ONBOARDING_MAX_OPEN_CONNS: ""
      # DB_ONBOARDING_MAX_IDLE_CONNS: ""
      # DB_TRANSACTION_MAX_OPEN_CONNS: ""
      # DB_TRANSACTION_MAX_IDLE_CONNS: ""

      # Balance Sync Worker
      BALANCE_SYNC_BATCH_SIZE: "100"
      BALANCE_SYNC_FLUSH_TIMEOUT_MS: "1000"
      BALANCE_SYNC_POLL_INTERVAL_MS: "500"

      # Multi-Tenant
      MULTI_TENANT_ENABLED: "false"
      # MULTI_TENANT_URL: "http://tenant-manager:4003"
      # MULTI_TENANT_SERVICE_API_KEY: ""
      # MULTI_TENANT_CONNECTIONS_CHECK_INTERVAL_SEC: ""
      # MULTI_TENANT_CACHE_TTL_SEC: "120"
      # MULTI_TENANT_CIRCUIT_BREAKER_THRESHOLD: "5"
      # MULTI_TENANT_CIRCUIT_BREAKER_TIMEOUT_SEC: "30"
      # MULTI_TENANT_REDIS_HOST: ""
      # MULTI_TENANT_REDIS_PORT: "6379"
      # MULTI_TENANT_REDIS_PASSWORD: ""
      # MULTI_TENANT_REDIS_TLS: "false"

      # Multi-Tenant (CRM only)
      # MULTI_TENANT_TIMEOUT: "30"
      # MULTI_TENANT_MAX_TENANT_POOLS: "100"
      # MULTI_TENANT_IDLE_TIMEOUT_SEC: "300"

      # RabbitMQ Circuit Breaker
      RABBITMQ_CIRCUIT_BREAKER_CONSECUTIVE_FAILURES: "15"
      RABBITMQ_CIRCUIT_BREAKER_FAILURE_RATIO: "50"
      RABBITMQ_CIRCUIT_BREAKER_INTERVAL: "120"
      RABBITMQ_CIRCUIT_BREAKER_MAX_REQUESTS: "3"
      RABBITMQ_CIRCUIT_BREAKER_MIN_REQUESTS: "10"
      RABBITMQ_CIRCUIT_BREAKER_TIMEOUT: "30"
      RABBITMQ_CIRCUIT_BREAKER_HEALTH_CHECK_INTERVAL: "30"
      RABBITMQ_CIRCUIT_BREAKER_HEALTH_CHECK_TIMEOUT: "10"

      # Audit Logging
      AUDIT_LOG_ENABLED: "false"
      RABBITMQ_AUDIT_EXCHANGE: "audit.append_log.exchange"
      RABBITMQ_AUDIT_KEY: "audit.append_log.key"

      # Transaction Events
      RABBITMQ_TRANSACTION_EVENTS_ENABLED: "false"
      RABBITMQ_TRANSACTION_EVENTS_EXCHANGE: "transaction.transaction_events.exchange"

      # Async Transaction Processing
      RABBITMQ_TRANSACTION_ASYNC: "false"
      # RABBITMQ_NUMBERS_OF_WORKERS: "5"
      # RABBITMQ_NUMBERS_OF_PREFETCH: "10"

      # Bulk Recorder (requires RABBITMQ_TRANSACTION_ASYNC=true and BULK_RECORDER_ENABLED=true)
      BULK_RECORDER_ENABLED: "true"
      # BULK_RECORDER_SIZE: "0"
      # BULK_RECORDER_FLUSH_TIMEOUT_MS: ""
      # BULK_RECORDER_MAX_ROWS_PER_INSERT: ""

      # Pagination
      MAX_PAGINATION_MONTH_DATE_RANGE: "3"
      # MAX_PAGINATION_LIMIT: "100"

    secrets:
      # Onboarding Module
      DB_ONBOARDING_PASSWORD: ""
      DB_ONBOARDING_REPLICA_PASSWORD: ""
      MONGO_ONBOARDING_PASSWORD: ""

      # Transaction Module
      DB_TRANSACTION_PASSWORD: ""
      DB_TRANSACTION_REPLICA_PASSWORD: ""
      MONGO_TRANSACTION_PASSWORD: ""

      # Shared
      REDIS_PASSWORD: ""
      RABBITMQ_DEFAULT_PASS: ""
      RABBITMQ_CONSUMER_PASS: ""
  ```
</CodeGroup>

## Suporte a secrets externos

<CodeGroup>
  ```yaml values.yaml theme={null}
  ledger:
    useExistingSecret: true
    existingSecretName: <existing-secret-name>
  ```
</CodeGroup>

## Referência de flags de deployment

| Flag                       | Padrão | Descrição                                                                        |
| :------------------------- | :----- | :------------------------------------------------------------------------------- |
| ledger.enabled             | true   | Habilita o serviço Ledger unificado                                              |
| onboarding.enabled         | —      | Serviço dividido legado — removido das versões atuais do chart (apenas migração) |
| transaction.enabled        | —      | Serviço dividido legado — removido das versões atuais do chart (apenas migração) |
| migration.allowAllServices | false  | Flag oculta para permitir todos os serviços simultaneamente                      |

## Referência de variáveis de ambiente

Descrições detalhadas para as variáveis que não são autoexplicativas a partir do bloco YAML acima.

### Pools de conexão de banco de dados

| Variável                        | Descrição                                                              | Padrão                         |
| :------------------------------ | :--------------------------------------------------------------------- | :----------------------------- |
| `DB_ONBOARDING_MAX_OPEN_CONNS`  | Máximo de conexões abertas com o banco PostgreSQL de Onboarding.       | Valor padrão do Go (ilimitado) |
| `DB_ONBOARDING_MAX_IDLE_CONNS`  | Máximo de conexões ociosas mantidas vivas para o banco de Onboarding.  | Valor padrão do Go (2)         |
| `DB_TRANSACTION_MAX_OPEN_CONNS` | Máximo de conexões abertas com o banco PostgreSQL de Transaction.      | Valor padrão do Go (ilimitado) |
| `DB_TRANSACTION_MAX_IDLE_CONNS` | Máximo de conexões ociosas mantidas vivas para o banco de Transaction. | Valor padrão do Go (2)         |

<Tip>
  Para cargas de trabalho em produção, defina limites explícitos de pool para evitar o esgotamento de conexões. Um ponto de partida comum: `MAX_OPEN_CONNS=25`, `MAX_IDLE_CONNS=10` por módulo de banco. Ajuste com base na sua configuração `max_connections` do PostgreSQL e no número de réplicas do Midaz.
</Tip>

### RabbitMQ

| Variável         | Descrição                                                                                          | Padrão |
| :--------------- | :------------------------------------------------------------------------------------------------- | :----- |
| `RABBITMQ_VHOST` | Virtual host do RabbitMQ. Útil para isolar o tráfego do Midaz em clusters RabbitMQ compartilhados. | `/`    |

### Audit logging

Quando habilitado, o Midaz publica logs de auditoria detalhados em nível de operação em um exchange do RabbitMQ após cada transação. O payload de auditoria inclui os dados completos da operação (valores, contas, saldos antes/depois) serializados como JSON. Você consome esses eventos vinculando sua própria fila ao exchange de auditoria.

| Variável                  | Descrição                                                    | Padrão                      |
| :------------------------ | :----------------------------------------------------------- | :-------------------------- |
| `AUDIT_LOG_ENABLED`       | Habilita o audit logging de transações.                      | `false`                     |
| `RABBITMQ_AUDIT_EXCHANGE` | Nome do exchange do RabbitMQ para as mensagens de auditoria. | `audit.append_log.exchange` |
| `RABBITMQ_AUDIT_KEY`      | Routing key para as mensagens de auditoria.                  | `audit.append_log.key`      |

### Eventos de transação

| Variável                               | Descrição                                                                                                                          | Padrão                                    |
| :------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------- |
| `RABBITMQ_TRANSACTION_EVENTS_ENABLED`  | Habilita a publicação de eventos de transação em tempo real. Veja [Event publisher](/pt/midaz/event-publisher) para mais detalhes. | `false`                                   |
| `RABBITMQ_TRANSACTION_EVENTS_EXCHANGE` | Nome do exchange do RabbitMQ para os eventos de transação.                                                                         | `transaction.transaction_events.exchange` |

### Processamento assíncrono de transações

Quando `RABBITMQ_TRANSACTION_ASYNC` está habilitado, o Midaz processa transações de forma assíncrona via consumidores RabbitMQ, em vez de inline durante a requisição à API. O bulk recorder ainda agrupa gravações no banco de dados para maior throughput.

<Note>
  As variáveis `BULK_RECORDER_*` só têm efeito quando **ambas** `RABBITMQ_TRANSACTION_ASYNC=true` e `BULK_RECORDER_ENABLED=true` estão ativas.
</Note>

| Variável                            | Descrição                                                                                                           | Padrão     |
| :---------------------------------- | :------------------------------------------------------------------------------------------------------------------ | :--------- |
| `RABBITMQ_TRANSACTION_ASYNC`        | Habilita o processamento assíncrono de transações via consumidores RabbitMQ.                                        | `false`    |
| `RABBITMQ_NUMBERS_OF_WORKERS`       | Número de goroutines de workers consumidores assíncronos.                                                           | `5`        |
| `RABBITMQ_NUMBERS_OF_PREFETCH`      | Contagem de prefetch do RabbitMQ por worker — controla quantas mensagens cada worker armazena em buffer de uma vez. | `10`       |
| `BULK_RECORDER_ENABLED`             | Habilita o modo de inserção em lote para gravações de operações quando o processamento assíncrono está ativo.       | `true`     |
| `BULK_RECORDER_SIZE`                | Tamanho do lote para inserções em bulk. Defina como `0` para dimensionamento automático baseado na carga.           | `0` (auto) |
| `BULK_RECORDER_FLUSH_TIMEOUT_MS`    | Tempo máximo (em milissegundos) para aguardar antes de fazer flush de um lote incompleto.                           | —          |
| `BULK_RECORDER_MAX_ROWS_PER_INSERT` | Número máximo de linhas por instrução INSERT durante gravações em bulk.                                             | —          |

### Paginação

| Variável                          | Descrição                                                                                                                                                               | Padrão |
| :-------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----- |
| `MAX_PAGINATION_MONTH_DATE_RANGE` | Range máximo de datas (em meses) permitido para as consultas paginadas. Limita o quão para trás os endpoints de listagem podem consultar. Use `0` para range ilimitado. | `3`    |
| `MAX_PAGINATION_LIMIT`            | Número máximo de itens retornados por página nas respostas paginadas da API.                                                                                            | `100`  |

<Note>
  O limite do range de datas da paginação evita full table scans custosos em grandes volumes de dados. Se seu caso de uso precisa consultar dados históricos além de 3 meses, aumente esse valor ou defina como `0` — mas monitore o desempenho das consultas.
</Note>