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

# Migrating from v4.x to v5.x

> Migrate your Midaz Helm deployment from v4.x to v5.x — follow the pre-upgrade checklist, run migrations, and validate the new release.

## Pre-upgrade checklist

<Steps>
  <Step>
    Backup existing Helm releases:

    <CodeGroup>
      ```bash Shell theme={null}
      helm get values -n midaz midaz > midaz-v4-backup.yaml
      ```
    </CodeGroup>
  </Step>

  <Step>
    **Decision required**: Choose your deployment strategy (Ledger service or legacy Onboarding/Transaction).
  </Step>

  <Step>
    If migrating to Ledger service, prepare new secrets with module-specific prefixes.
  </Step>

  <Step>
    Schedule a maintenance window.
  </Step>
</Steps>

## Breaking changes in v5.x

### New Ledger service available

Starting from version 5.0, the **Ledger service** is available (`ledger.enabled: false` by default). When enabled, this service combines the functionality of both `onboarding` and `transaction` modules into a single deployment.

<Warning>
  The separate `onboarding` and `transaction` services will become legacy in a future release. The unified Ledger service will become mandatory. We strongly recommend planning your migration to the Ledger service.
</Warning>

**Default values:**

| Setting             | v4.x (before) | v5.x (after)                                |
| :------------------ | :------------ | :------------------------------------------ |
| ledger.enabled      | N/A           | false                                       |
| onboarding.enabled  | true          | true (auto-disabled when ledger is enabled) |
| transaction.enabled | true          | true (auto-disabled when ledger is enabled) |

**Impact when enabling Ledger:**

* The `midaz-onboarding` and `midaz-transaction` deployments will be removed.
* A new `midaz-ledger` deployment will be created.
* Ingresses will automatically redirect to the Ledger service (DNS compatibility maintained).
* Environment variables and secrets structure changes (module-specific prefixes).

### App version bump

Midaz has been bumped to **v3.5.3**.

<Note>
  Check the [app changelog](https://github.com/LerianStudio/midaz/blob/main/CHANGELOG.md) for the complete list of changes.
</Note>

## Migration options

### Option 1: keep using Onboarding and Transaction (gradual migration)

Add the following to your values override to maintain the current behavior:

<CodeGroup>
  ```yaml values.yaml theme={null}
  ledger:
    enabled: false

  onboarding:
    enabled: true

  transaction:
    enabled: true
  ```
</CodeGroup>

This allows you to upgrade the chart version without changing your infrastructure.

### Option 2: run all services simultaneously (testing/migration period)

Use the hidden `migration.allowAllServices` flag to run all three services during the migration:

<CodeGroup>
  ```yaml values.yaml theme={null}
  ledger:
    enabled: true

  onboarding:
    enabled: true

  transaction:
    enabled: true

  migration:
    allowAllServices: true
  ```
</CodeGroup>

<Warning>
  This mode is intended for testing and migration only. Do not use in production long-term.
</Warning>

### Option 3: migrate to Ledger (recommended)

Accept the new architecture and migrate to the unified Ledger service:

<Steps>
  <Step>
    **Before upgrading**: Ensure your databases are ready (same databases, new environment variable names).
  </Step>

  <Step>
    **Update secrets**: Create new secrets with module-specific prefixes (see [Configuration reference](/en/platform/helm/midaz/midaz-configuration-reference)).
  </Step>

  <Step>
    **Upgrade**: Run helm upgrade with the new chart version.
  </Step>

  <Step>
    **Verify**: Check that the Ledger service is healthy and ingresses are working.
  </Step>
</Steps>

<CodeGroup>
  ```yaml values.yaml theme={null}
  ledger:
    enabled: true

  onboarding:
    enabled: false

  transaction:
    enabled: false
  ```
</CodeGroup>

## New features in v5.x

### Unified Ledger service

A new Ledger service that combines `onboarding` and `transaction` modules into a single deployment.

**Key characteristics:**

* Single HTTP endpoint (port 3000 by default)
* Separate database configurations for each module
* Shared Redis and RabbitMQ connections
* New Balance Sync Worker for background processing

**New environment variables:**

<CodeGroup>
  ```yaml values.yaml theme={null}
  # Balance Sync Worker
  BALANCE_SYNC_WORKER_ENABLED: "false"
  BALANCE_SYNC_MAX_WORKERS: "5"
  ```
</CodeGroup>

<Note>
  These environment variables have been renamed in later versions. The current variable names are: `BALANCE_SYNC_BATCH_SIZE`, `BALANCE_SYNC_FLUSH_TIMEOUT_MS`, and `BALANCE_SYNC_POLL_INTERVAL_MS`. See the Configuration Reference for current defaults.
</Note>

### Ingress redirection to Ledger

When Ledger is enabled, existing ingresses automatically redirect traffic to the Ledger service, maintaining DNS compatibility.

| ledger.enabled | migration.allowAllServices | onboarding ingress target | transaction ingress target |
| :------------- | :------------------------- | :------------------------ | :------------------------- |
| false          | false (default)            | midaz-onboarding          | midaz-transaction          |
| true           | false (default)            | midaz-ledger              | midaz-ledger               |
| true           | true                       | midaz-onboarding          | midaz-transaction          |

### CRM service integration

The CRM service is now available as an integrated component, moving from `midaz-plugins` to `midaz` namespace.

<Tip>
  For more details, refer to the [CRM Documentation](/en/midaz/crm/crm-overview).
</Tip>

**Migration from plugin-crm:**

<Steps>
  <Step>
    Deploy the new CRM in the midaz namespace:

    <CodeGroup>
      ```yaml values.yaml theme={null}
      crm:
        enabled: true
        configmap:
          MONGO_HOST: "midaz-mongodb"
          MONGO_NAME: "crm"
      ```
    </CodeGroup>
  </Step>

  <Step>
    Migrate your data from the old MongoDB to the new one (if using separate databases).
  </Step>

  <Step>
    Update your ingress/DNS to point to the new CRM service.
  </Step>

  <Step>
    Remove the old plugin-crm release from midaz-plugins namespace.
  </Step>
</Steps>

## Upgrade command

<CodeGroup>
  ```bash Shell theme={null}
  helm upgrade midaz oci://registry-1.docker.io/lerianstudio/midaz-helm --version 5.x.x -n midaz
  ```
</CodeGroup>

## Rollback procedure

<CodeGroup>
  ```bash Shell theme={null}
  # List release history
  helm history midaz -n midaz

  # Rollback to previous version
  helm rollback midaz <REVISION> -n midaz

  # Or explicitly disable ledger
  helm upgrade midaz oci://registry-1.docker.io/lerianstudio/midaz-helm \
    --set ledger.enabled=false \
    --set onboarding.enabled=true \
    --set transaction.enabled=true \
    -n midaz
  ```
</CodeGroup>

## Common issues

**Ledger service fails to start**

* Verify that all module-specific environment variables and secrets are configured with the new prefixes (`DB_ONBOARDING_*`, `DB_TRANSACTION_*`, etc.).

**Ingress not routing to Ledger**

* Ensure `ledger.enabled: true` and `migration.allowAllServices` is not set to `true`.

**Missing secrets after enabling Ledger**

* Create new secrets with module prefixes:
  * `DB_ONBOARDING_PASSWORD` instead of `DB_PASSWORD`
  * `DB_TRANSACTION_PASSWORD` instead of `DB_PASSWORD`
  * `MONGO_ONBOARDING_PASSWORD` instead of `MONGO_PASSWORD`
  * `MONGO_TRANSACTION_PASSWORD` instead of `MONGO_PASSWORD`