Migrando do Odoo 17/18 para o Odoo 19: Guia Completo

A migração é uma das operações de maior risco no ciclo de vida de um ERP: perda de dados, módulos personalizados quebrados e tempo de inatividade prolongado são riscos reais que exigem planejamento e execução cuidadosos.

Este guia fornece uma metodologia de migração prática e passo a passo para organizações que estão migrando do Odoo 17 ou Odoo 18 para o Odoo 19 Enterprise. Ele cobre tudo, desde avaliação inicial e mapeamento de dados até atualizações de módulos personalizados, procedimentos de teste e plano de transição de entrada em operação.

Principais conclusões

• A compatibilidade do módulo personalizado deve ser verificada em relação às alterações da API do Odoo 19
• A migração de dados é executada através da plataforma de atualização oficial do Odoo ou OpenUpgrade
• Um ambiente de testes paralelo é obrigatório antes da transição da produção
• Os períodos financeiros devem ser encerrados antes da transição para evitar problemas de reconciliação
• Todas as integrações de terceiros precisam de nova verificação após a migração
• O plano de reversão deve ser documentado e testado antes de entrar em operação

---

Planejamento de Migração: Fase de Avaliação

Antes de escrever um único script de migração, invista tempo em uma avaliação completa. As migrações falham na maioria das vezes devido ao planeamento inadequado e não à complexidade técnica.

Etapa 1: inventariar seu ambiente atual

Documente todos os componentes da sua instalação atual do Odoo:

Current Environment Inventory:
- Odoo version: 17.0.x or 18.0.x
- Edition: Community or Enterprise
- Database size: X GB, Y records in sale.order, Z in account.move
- Installed modules: [list all modules]
- Custom modules: [list with developer contact]
- Third-party connectors: [Amazon, Shopify, etc.]
- Active integrations: [API, webhooks, cron jobs]
- Customized reports: [list]
- Custom fields (Studio or code): [list]
- Server specs: RAM, CPU, disk
- PostgreSQL version:

Etapa 2: Classificar módulos personalizados

Para cada módulo personalizado, determine:

---

Escolhendo seu caminho de migração

Caminho 1: Serviço de atualização oficial Odoo

Odoo SA fornece um serviço de atualização automatizado em upgrade.odoo.com. Você envia seu banco de dados, eles executam scripts de migração desenvolvidos e mantidos pela Odoo SA e você recebe um banco de dados atualizado.

Prós:

• Suporte oficial e testes da Odoo SA
• Lida com alterações no esquema do banco de dados automaticamente
• Adequado para Odoo padrão com personalizações mínimas

Contras:

• Requer o envio de dados de produção aos servidores do Odoo
• Controle limitado sobre o processo de migração
• A migração do módulo personalizado é de sua responsabilidade

Caminho 2: OpenUpgrade (Ferramenta da Comunidade)

OpenUpgrade é um projeto de código aberto que fornece scripts de migração para Community.

Caminho 3: Nova instalação com importação de dados

Para instâncias altamente customizadas ou versões muito antigas:

1. Configure uma nova instância do Odoo 19 Enterprise
2. Reconfigure todos os módulos e configurações
3. Exporte dados críticos do sistema antigo
4. Importe através da ferramenta de importação do Odoo ou scripts de migração personalizados
5. Insira novamente manualmente os saldos iniciais para contabilidade

Esse caminho é mais lento, mas fornece o ponto de partida mais limpo.

Recomendado para a maioria das migrações Odoo 17/18 → 19: Caminho 1 ou 2 combinado com um esforço paralelo de redesenvolvimento de módulo personalizado.

---

Preparação pré-migração

Fechar períodos financeiros:

Antes da migração:

1. Bloqueie todos os períodos anteriores ao mês atual no Odoo Accounting
2. Execute os relatórios antigos de contas a receber e a pagar e reconcilie as diferenças
3. Reconcilie todos os extratos bancários até a data da migração
4. Lançar todos os projetos de fatura que devem ser incluídos nos dados históricos

Faça backup de tudo:

# PostgreSQL backup
pg_dump -h localhost -U odoo_user -Fc odoo_production > \
    odoo_prod_backup_$(date +%Y%m%d_%H%M%S).dump

# Filestore backup (attachments, images)
tar -czf odoo_filestore_$(date +%Y%m%d).tar.gz \
    /var/lib/odoo/.local/share/Odoo/filestore/

# Configuration backup
cp /etc/odoo/odoo.conf odoo_conf_backup_$(date +%Y%m%d).conf

---

Configurando o ambiente de migração

Configuração de infraestrutura:

# Install Odoo 19 Enterprise on migration server

# Install PostgreSQL 15+
sudo apt install postgresql-15 postgresql-contrib

# Install Python 3.12 and dependencies
sudo apt install python3.12 python3.12-dev python3.12-venv \
    libxml2-dev libxslt1-dev libldap2-dev libsasl2-dev \
    libtiff5-dev libjpeg8-dev libopenjp2-7-dev zlib1g-dev \
    libfreetype6-dev liblcms2-dev libwebp-dev libharfbuzz-dev \
    libfribidi-dev libxcb1-dev

# Clone Odoo 19 Enterprise
git clone https://github.com/odoo/odoo.git -b 19.0 /opt/odoo19
git clone https://github.com/odoo/enterprise.git -b 19.0 /opt/odoo19-enterprise

# Install Python dependencies
pip3.12 install -r /opt/odoo19/requirements.txt

---

Migração de módulo personalizado

Esta fase é a mais demorada. Cada módulo personalizado requer:

1. Atualizar versão do manifesto:

# Change from:
'version': '17.0.1.0.0',
# To:
'version': '19.0.1.0.0',

2. Atualizar sintaxe de visualização:

<!-- Old (v16 and earlier): -->
<field name="state" attrs="{'invisible': [('active', '=', False)]}"/>

<!-- New (v17+): -->
<field name="state" invisible="not active"/>

3. Teste cada módulo de forma independente:

# Install and test each custom module
python3 odoo-bin -d test_db -i my_custom_module --stop-after-init
python3 odoo-bin -d test_db --test-enable -u my_custom_module

---

Validação e teste de dados

Validação de contagem de registros:

Compare as contagens de registros entre o banco de dados de origem e o banco de dados migrado:

# Run on both source and target to compare
models_to_check = [
    'res.partner', 'product.template', 'product.product',
    'sale.order', 'purchase.order', 'account.move',
    'stock.quant', 'mrp.production', 'hr.employee'
]

for model in models_to_check:
    count = env[model].search_count([])
    print(f"{model}: {count}")

Lista de verificação de testes de aceitação do usuário:

• [] Todos os menus e itens de navegação acessíveis
• [] Principais fluxos de trabalho: pedido de venda → entrega → fatura → pagamento
• [] Contabilidade: lançamentos contábeis manuais, conciliação bancária, relatórios
• Estoque: recebimentos, entregas, avaliação de estoque
• [] Fabricação: lista técnica, ordens de serviço, verificações de qualidade (se aplicável)
• RH: funcionários, gestão de licenças, folha de pagamento (se aplicável)
• [] Funcionalidade do módulo personalizado verificada por usuários empresariais
• [] Os relatórios são gerados corretamente e correspondem à saída pré-migração
• [] Integrações externas (API, webhooks) testadas em teste

---

Plano de transição para entrada em operação

Planejamento da janela de transição:

Escolha uma janela de transição com impacto mínimo nos negócios:

• Fim de semana (sábado à noite a domingo de manhã para a maioria das empresas)
• Fim do mês fiscal (simplifica a entrada do saldo de abertura)
• Após o último dia útil antes de um feriado (tempo de buffer extra)

Lista de verificação de transição:

T-48 hours:
[ ] Final communication to all users about downtime window
[ ] Freeze all non-critical transactions in old system
[ ] Verify migration server is ready
[ ] Complete last data validation run

T-0 (Cutover Start):
[ ] Put old system in maintenance mode (disable user access)
[ ] Create final backup of production database
[ ] Run final migration on this backup
[ ] Verify record counts and financial balances
[ ] Test all critical workflows
[ ] DNS/URL cutover to new system
[ ] Smoke test from user devices (desktop, mobile)

T+2 hours (Go-Live Verification):
[ ] All users can log in
[ ] Create test sale order, confirm, ship, invoice
[ ] Verify email sending works
[ ] Check integrations are receiving/sending data
[ ] Monitor error logs for first 30 minutes

Plano de reversão:

Se problemas críticos forem encontrados durante a transição:

1. Mude o DNS de volta para o servidor antigo
2. Reative o sistema antigo para usuários
3. Documente todos os problemas encontrados
4. Agendar janela de migração de acompanhamento

---

Perguntas frequentes

Posso pular do Odoo 17 diretamente para o Odoo 19 ou devo passar pelo 18?

Usando o serviço de atualização oficial do Odoo, normalmente você pode ir diretamente de 17 para 19. Os scripts de migração do Odoo SA lidam com saltos de várias versões. Sempre verifique o repositório OpenUpgrade para as versões específicas que você precisa.

Quanto tempo leva uma migração típica do Odoo?

A linha do tempo depende muito do nível de personalização. A migração em si (atualização do banco de dados) leva horas; o tempo está em testes, atualizações de módulos e validação.

O que acontece com as personalizações do Studio durante a migração?

As personalizações do Studio são armazenadas como dados padrão do Odoo (visualizações, campos, automações) e migram através do processo padrão de atualização do banco de dados. No entanto, algumas personalizações de visualização podem precisar de revisão manual se o Odoo 19 alterar a estrutura subjacente do formulário. Sempre teste todas as personalizações do Studio após a migração.

Preciso inserir novamente os saldos iniciais após a migração?

Não, se você migrar o banco de dados diretamente. Todos os lançamentos históricos e saldos são transferidos com o banco de dados. Se você escolher o caminho "nova instalação com importação de dados", precisará inserir os saldos iniciais a partir da data de transição, o que requer uma coordenação cuidadosa com sua equipe de contabilidade.

---

Próximas etapas

As migrações Odoo são projetos de alto risco que impactam diretamente a continuidade dos negócios. A diferença entre uma migração tranquila e uma migração dolorosa se resume à preparação, conhecimento e uma metodologia de testes rigorosa.

Nossa metodologia de migração abrange avaliação completa, atualizações de módulos personalizados, testes paralelos e um plano de transição documentado com procedimentos de reversão.

Solicite uma avaliação de migração Odoo da ECOSIRE →