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

# Configuration reference

> Reference all Ledger service Helm parameters — module-specific databases, external secrets, and deployment flags for Midaz on Kubernetes.

## Ledger service configuration reference

***

The Ledger service uses module-specific database configurations:

<CodeGroup>
  ```yaml values.yaml expandable theme={null}
  ledger:
    enabled: false
    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: "3000"
      SERVER_ADDRESS: ":3000"

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

## External secrets support

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

## Deployment flags reference

| Flag                       | Default | Description                                                |
| :------------------------- | :------ | :--------------------------------------------------------- |
| ledger.enabled             | false   | Enables the unified Ledger service                         |
| onboarding.enabled         | true    | Enables onboarding (auto-disabled when ledger is enabled)  |
| transaction.enabled        | true    | Enables transaction (auto-disabled when ledger is enabled) |
| migration.allowAllServices | false   | Hidden flag to allow all services simultaneously           |

## Environment variables reference

Detailed descriptions for variables that aren't self-explanatory from the YAML block above.

### Database connection pools

| Variable                        | Description                                                       | Default                |
| :------------------------------ | :---------------------------------------------------------------- | :--------------------- |
| `DB_ONBOARDING_MAX_OPEN_CONNS`  | Maximum open connections to the Onboarding PostgreSQL database.   | Go default (unlimited) |
| `DB_ONBOARDING_MAX_IDLE_CONNS`  | Maximum idle connections kept alive for the Onboarding database.  | Go default (2)         |
| `DB_TRANSACTION_MAX_OPEN_CONNS` | Maximum open connections to the Transaction PostgreSQL database.  | Go default (unlimited) |
| `DB_TRANSACTION_MAX_IDLE_CONNS` | Maximum idle connections kept alive for the Transaction database. | Go default (2)         |

<Tip>
  For production workloads, set explicit pool limits to prevent connection exhaustion. A common starting point: `MAX_OPEN_CONNS=25`, `MAX_IDLE_CONNS=10` per database module. Tune based on your PostgreSQL `max_connections` setting and the number of Midaz replicas.
</Tip>

### RabbitMQ

| Variable         | Description                                                                            | Default |
| :--------------- | :------------------------------------------------------------------------------------- | :------ |
| `RABBITMQ_VHOST` | RabbitMQ virtual host. Useful for isolating Midaz traffic in shared RabbitMQ clusters. | `/`     |

### Audit logging

When enabled, Midaz publishes detailed operation-level audit logs to a RabbitMQ exchange after each transaction. The audit payload includes the full operation data (amounts, accounts, balances before/after) serialized as JSON. You consume these events by binding your own queue to the audit exchange.

| Variable                  | Description                                | Default                     |
| :------------------------ | :----------------------------------------- | :-------------------------- |
| `AUDIT_LOG_ENABLED`       | Enable transaction audit logging.          | `false`                     |
| `RABBITMQ_AUDIT_EXCHANGE` | RabbitMQ exchange name for audit messages. | `audit.append_log.exchange` |
| `RABBITMQ_AUDIT_KEY`      | Routing key for audit messages.            | `audit.append_log.key`      |

### Transaction events

| Variable                               | Description                                                                                                  | Default                                   |
| :------------------------------------- | :----------------------------------------------------------------------------------------------------------- | :---------------------------------------- |
| `RABBITMQ_TRANSACTION_EVENTS_ENABLED`  | Enable real-time transaction event publishing. See [Event publisher](/en/midaz/event-publisher) for details. | `false`                                   |
| `RABBITMQ_TRANSACTION_EVENTS_EXCHANGE` | RabbitMQ exchange name for transaction events.                                                               | `transaction.transaction_events.exchange` |

### Async transaction processing

When `RABBITMQ_TRANSACTION_ASYNC` is enabled, Midaz processes transactions asynchronously through RabbitMQ consumers instead of inline during the API request. The bulk recorder further batches database writes for higher throughput.

<Note>
  `BULK_RECORDER_*` variables only take effect when **both** `RABBITMQ_TRANSACTION_ASYNC=true` and `BULK_RECORDER_ENABLED=true`.
</Note>

| Variable                            | Description                                                                                  | Default    |
| :---------------------------------- | :------------------------------------------------------------------------------------------- | :--------- |
| `RABBITMQ_TRANSACTION_ASYNC`        | Enables asynchronous transaction processing via RabbitMQ consumers.                          | `false`    |
| `RABBITMQ_NUMBERS_OF_WORKERS`       | Number of async consumer worker goroutines.                                                  | `5`        |
| `RABBITMQ_NUMBERS_OF_PREFETCH`      | RabbitMQ prefetch count per worker — controls how many messages each worker buffers at once. | `10`       |
| `BULK_RECORDER_ENABLED`             | Enables bulk insert mode for operation writes when async processing is active.               | `true`     |
| `BULK_RECORDER_SIZE`                | Batch size for bulk inserts. Set to `0` for automatic sizing based on load.                  | `0` (auto) |
| `BULK_RECORDER_FLUSH_TIMEOUT_MS`    | Maximum time (in milliseconds) to wait before flushing an incomplete batch.                  | —          |
| `BULK_RECORDER_MAX_ROWS_PER_INSERT` | Maximum number of rows per INSERT statement during bulk writes.                              | —          |

### Pagination

| Variable                          | Description                                                                                                                                 | Default |
| :-------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------ | :------ |
| `MAX_PAGINATION_MONTH_DATE_RANGE` | Maximum date range (in months) allowed for paginated queries. Limits how far back list endpoints can query. Set to `0` for unlimited range. | `3`     |
| `MAX_PAGINATION_LIMIT`            | Maximum number of items returned per page in paginated API responses.                                                                       | `100`   |

<Note>
  The pagination date range limit prevents expensive full-table scans on large datasets. If your use case requires querying historical data beyond 3 months, increase this value or set it to `0` — but monitor query performance accordingly.
</Note>