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

A atualização para o Odoo 19 Enterprise oferece melhorias significativas no desempenho, na experiência do usuário e nos recursos assistidos por IA. Mas 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 migração para Odoo 19 requer a atualização de uma versão principal por vez (17→18→19 ou 17→19 diretamente com OpenUpgrade)
• 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
• Planeje um cronograma total de migração de 3 a 8 semanas, dependendo da complexidade
• 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: (minimum 15 required for Odoo 19)

Etapa 2: Classificar módulos personalizados

Para cada módulo personalizado, determine:

Etapa 3: Identifique alterações importantes no Odoo 19

Principais mudanças entre Odoo 17/18 e Odoo 19 que afetam módulos personalizados:

• OWL 3.x: os componentes frontend devem ser migrados dos padrões OWL 2.x
• Python 3.12: alguma sintaxe do Python 3.10/3.11 pode precisar de ajustes
• PostgreSQL 15+: Versão mínima necessária; alguns padrões de consulta mudam
• Descontinuação da API: vários métodos _legacy removidos; verifique se há _multi → _create_multi
• Mecanismo de relatório: algumas variáveis de relatório QWeb renomeadas
• Refatoração de movimentação de conta: alterações na estrutura de linha account.move afetam personalizações contábeis

---

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:

• Não suporta módulos personalizados
• 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 e Enterprise.

# Clone OpenUpgrade for Odoo 19
git clone https://github.com/OCA/OpenUpgrade.git -b 19.0

# Install upgrade dependencies
pip install openupgradelib

# Run migration
python odoo-bin --config=upgrade.conf \
    --update=all \
    --load=base,web,openupgrade_framework

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 (semanas 1-2)

Preparação do banco de dados:

-- Run on source database before export
-- Identify orphaned records
SELECT id, name FROM res_partner WHERE active = FALSE AND id NOT IN (
    SELECT partner_id FROM sale_order
    UNION SELECT partner_id FROM account_move
    UNION SELECT partner_id FROM stock_picking
);

-- Archive old draft records (reduces migration time)
UPDATE sale_order SET active = FALSE
WHERE state = 'draft' AND date_order < NOW() - INTERVAL '2 years';

-- Verify accounting reconciliation
SELECT COUNT(*) FROM account_move_line
WHERE reconciled = FALSE AND debit != credit;

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 -p 5433 -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

Revisão do código do módulo personalizado:

Para cada módulo personalizado, execute uma verificação de compatibilidade:

# Check for deprecated patterns
grep -r "execute_kw" custom_modules/   # Still valid in v19
grep -r "browse\(\[" custom_modules/  # Should be browse(ids) not browse([ids])
grep -r "_multi" custom_modules/      # Check for renamed methods
grep -r "account\.move\.line\." custom_modules/  # Account refactoring affected
grep -r "@api\.one" custom_modules/   # Removed in v14, ensure not present
grep -r "@api\.multi" custom_modules/ # Removed in v14, ensure not present

---

Configurando o ambiente de migração (Semana 2-3)

Configuração de infraestrutura:

# Install Odoo 19 Enterprise on migration server
# Requirements: Ubuntu 22.04/24.04, PostgreSQL 15+, Python 3.12

# 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

Restaurar banco de dados de origem para servidor de migração:

# Create target database
createdb -h localhost -U postgres odoo_migration_test

# Restore backup
pg_restore -h localhost -U postgres -d odoo_migration_test \
    odoo_prod_backup_YYYYMMDD.dump

# Run Odoo upgrade
python3 /opt/odoo19/odoo-bin \
    -d odoo_migration_test \
    -u all \
    --without-demo=all \
    --stop-after-init

---

Migração de módulo personalizado (semanas 3 a 5)

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 compatibilidade com Python:

# Old pattern (deprecated):
@api.multi
def my_method(self):
    for record in self:
        pass

# New pattern:
def my_method(self):
    for record in self:
        pass

3. Atualizar sintaxe de visualização:

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

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

4. Atualize os componentes OWL (se houver widgets de frontend):

OWL 3.x introduz alterações de reatividade. Se seus módulos usam widgets JavaScript personalizados:

// Old OWL 2.x:
class MyWidget extends Component {
    static template = 'MyModule.MyWidget';
    willStart() { ... }
}

// New OWL 3.x:
class MyWidget extends Component {
    static template = 'MyModule.MyWidget';
    setup() {
        onWillStart(async () => { ... });
    }
}

5. 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 (semanas 5 a 6)

Validação de dados financeiros:

-- Verify balance sheet balances (assets = liabilities + equity)
SELECT
    SUM(CASE WHEN account_type LIKE 'asset%' THEN balance ELSE 0 END) as assets,
    SUM(CASE WHEN account_type LIKE 'liability%' THEN balance ELSE 0 END) as liabilities,
    SUM(CASE WHEN account_type = 'equity' THEN balance ELSE 0 END) as equity
FROM account_account aa
JOIN account_move_line aml ON aml.account_id = aa.id
JOIN account_move am ON aml.move_id = am.id
WHERE am.state = 'posted';

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 (semana 7 a 8)

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 (<5 minutos)
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. Com o OpenUpgrade, pode ser necessário ir de 17 a 18 a 19, dependendo dos scripts de migração disponíveis. 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. Uma instância padrão do Odoo com personalizações mínimas: 2 a 3 semanas. Moderadamente personalizado (5 a 10 módulos personalizados): 4 a 6 semanas. Altamente personalizado com integrações complexas: 8 a 16 semanas. 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.

Minha licença do Odoo Enterprise será transferida para a versão 19?

Sim. As assinaturas do Odoo Enterprise são independentes de versão. Sua assinatura anual cobre qualquer versão que você execute. Entre em contato com seu parceiro Odoo para obter o código Odoo 19 Enterprise se você não estiver acessando-o por meio do repositório Git do Odoo com suas credenciais corporativas.

---

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.

ECOSIRE migrou com sucesso dezenas de instâncias do Odoo das versões 13, 14, 15, 16, 17 e 18 para o Odoo 19 Enterprise. 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 →

Avaliaremos seu ambiente atual, identificaremos todos os riscos de migração e forneceremos um plano de migração de escopo fixo para que você saiba exatamente o que esperar antes da execução do primeiro script de migração.