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

# Migração de v3.x para v5.x

> Atualize seu deploy Helm do Midaz direto de v3.x para v5.x — trate breaking changes de ambas versões maiores em uma única migração.

Se você está atualizando diretamente de v3.x para v5.x, precisa lidar com as breaking changes de ambas as versões.

## Checklist pré-atualização

<Steps>
  <Step>
    Faça backup dos releases Helm existentes:

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

  <Step>
    **Crítico**: Faça backup dos dados e definições do RabbitMQ (breaking change do v4.x).
  </Step>

  <Step>
    **Decisão necessária**: Escolha sua estratégia de deployment - serviço Ledger ou legado Onboarding/Transaction (breaking change do v5.x).
  </Step>

  <Step>
    Se estiver migrando para o serviço Ledger, prepare novos secrets com prefixos específicos de módulo.
  </Step>

  <Step>
    Agende uma janela de manutenção.
  </Step>
</Steps>

## Breaking changes a serem tratadas

### Do v4.x: mudança da dependência do RabbitMQ

<Danger>
  A dependência do chart RabbitMQ mudou de Bitnami para Groundhog2k. Isso pode levar à **perda de dados PVC**. Faça backup dos dados do RabbitMQ antes de atualizar.
</Danger>

**Configuração obrigatória:**

<CodeGroup>
  ```yaml values.yaml theme={null}
  rabbitmq:
    authentication:
      erlangCookie:
        value: "<32+ printable characters without spaces>"
  ```
</CodeGroup>

### Do v5.x: novo serviço Ledger

<Warning>
  O serviço Ledger unificado está disponível e se tornará obrigatório em um release futuro. Planeje sua estratégia de migração.
</Warning>

**Escolha uma destas configurações:**

**Opção A: Manter serviços legado (migração gradual)**

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

  onboarding:
    enabled: true

  transaction:
    enabled: true

  rabbitmq:
    authentication:
      erlangCookie:
        value: "<32+ printable characters>"
  ```
</CodeGroup>

**Opção B: Migrar para o Ledger (recomendado)**

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

  onboarding:
    enabled: false

  transaction:
    enabled: false

  rabbitmq:
    authentication:
      erlangCookie:
        value: "<32+ printable characters>"
  ```
</CodeGroup>

Se estiver usando a Opção B, crie novos secrets com prefixos específicos de módulo:

* `DB_ONBOARDING_PASSWORD`, `DB_TRANSACTION_PASSWORD`
* `MONGO_ONBOARDING_PASSWORD`, `MONGO_TRANSACTION_PASSWORD`

## Comando de atualização

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

## O que muda a partir do v3.x

| Mudança              | Versão de Origem | Impacto                                           |
| :------------------- | :--------------- | :------------------------------------------------ |
| RabbitMQ Groundhog2k | v4.x             | Requer cookie Erlang, possível perda de dados PVC |
| BitnamiSecure images | v4.x             | PostgreSQL, MongoDB, Valkey usam imagens hardened |
| Official NGINX       | v4.x             | Revisar configurações NGINX customizadas          |
| Ledger service       | v5.x             | Novo serviço unificado (opcional mas recomendado) |
| CRM integration      | v5.x             | Move do namespace midaz-plugins para midaz        |

## Problemas comuns

**RabbitMQ falha ao iniciar**

* Certifique-se de que o cookie Erlang esteja configurado corretamente (32+ caracteres imprimíveis, sem espaços).

**Perda de dados PVC do RabbitMQ**

* Isso é esperado devido à mudança de dependência da v4.x de Bitnami para Groundhog2k. Exporte as definições do RabbitMQ antes de atualizar e restaure depois.

**O serviço Ledger falha ao iniciar**

* Verifique se todas as variáveis de ambiente e secrets específicas de módulo estão configuradas com os novos prefixos (`DB_ONBOARDING_*`, `DB_TRANSACTION_*`, etc.).

**Ingress não roteando para o Ledger**

* Certifique-se de que `ledger.enabled: true` e `migration.allowAllServices` não esteja definido como `true`.

**Secrets faltando após habilitar o Ledger**

* Crie novos secrets com prefixos de módulo:
  * `DB_ONBOARDING_PASSWORD` em vez de `DB_PASSWORD`
  * `DB_TRANSACTION_PASSWORD` em vez de `DB_PASSWORD`
  * `MONGO_ONBOARDING_PASSWORD` em vez de `MONGO_PASSWORD`
  * `MONGO_TRANSACTION_PASSWORD` em vez de `MONGO_PASSWORD`

**Problemas de configuração do NGINX**

* A atualização da v4.x substituiu o Bitnami NGINX por templates oficiais do NGINX. Revise os novos templates em `templates/console/` e atualize seus overrides.