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:

values.yaml

ledger:
  enabled: true
  name: "ledger"
  replicaCount: 2

  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_WORKER_ENABLED: "false"
    BALANCE_SYNC_MAX_WORKERS: "5"
    BALANCE_SYNC_BATCH_SIZE: "50"
    BALANCE_SYNC_FLUSH_TIMEOUT_MS: "500"
    BALANCE_SYNC_POLL_INTERVAL_MS: "50"

    # Multi-Tenant
    MULTI_TENANT_ENABLED: "false"
    # Point to your deployed https:// Tenant Manager endpoint so MULTI_TENANT_SERVICE_API_KEY
    # does not travel over cleartext HTTP. Only in local, non-production clusters you can use
    # in-cluster HTTP with an explicit opt-in: http://tenant-manager.<namespace>.svc.cluster.local:4026
    # MULTI_TENANT_URL: "https://tenant-manager.<your-domain>"
    # MULTI_TENANT_ALLOW_INSECURE_HTTP: "true" # Local development only; never enable in production.
    # 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

values.yaml

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

Deployment flags reference

Flag	Default	Description
ledger.enabled	true	Enables the unified Ledger service

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.	100
BULK_RECORDER_MAX_ROWS_PER_INSERT	Maximum number of rows per INSERT statement during bulk writes.	1000

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.