Configuration reference

Ledger service configuration reference

The Ledger service uses module-specific database configurations:

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

External secrets support

ledger:
  useExistingSecret: true
  existingSecretName: <existing-secret-name>

Deployment flags reference

Flag	Default	Description
ledger.enabled	true	Enables the unified Ledger service
onboarding.enabled	—	Legacy split service — removed from current chart versions (migration only)
transaction.enabled	—	Legacy split service — removed from current chart versions (migration only)
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)

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.

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

BULK_RECORDER_* variables only take effect when both RABBITMQ_TRANSACTION_ASYNC=true and BULK_RECORDER_ENABLED=true.

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`

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.

​Ledger service configuration reference

​External secrets support

​Deployment flags reference

​Environment variables reference

​Database connection pools

​RabbitMQ

​Audit logging

​Transaction events

​Async transaction processing

​Pagination

Ledger service configuration reference

External secrets support

Deployment flags reference

Environment variables reference

Database connection pools

RabbitMQ

Audit logging

Transaction events

Async transaction processing

Pagination