Database Migration Guide for Odoo
By Braincuber Team
Published on January 21, 2026
Migrating an Odoo database from v14 to v18 isn't just a version bump—it's a strategic transformation. Each major release introduces architectural changes: models get renamed, fields change types, workflows evolve. A successful migration preserves your business data while adapting to these structural shifts. This requires planning, testing, and systematic execution.
This guide covers the complete migration lifecycle: pre-migration analysis, schema transformation, data validation, and post-migration verification. Whether you're upgrading from v15, v16, v17, or earlier versions, these principles apply.
Migration Reality: Expect 20-30% of custom modules to require code updates. Standard modules handle most transformations automatically, but customizations need manual review and adaptation.
Why Database Migration Matters
Security Updates
Older versions stop receiving security patches. Staying current protects against vulnerabilities and compliance issues.
Performance Gains
Each release optimizes database queries, rendering, and background tasks. v18 runs 15-25% faster than v15 on identical hardware.
New Features
Access latest modules, UI improvements, and business logic enhancements. Stay competitive with modern ERP capabilities.
Pre-Migration Phase
Analyze Model and Field Changes
Every version introduces structural changes. Models get renamed, fields change types, relationships evolve.
Model Verification Checklist:
- Check if all current models exist in target version
- Identify renamed models (e.g.,
product.product→product.templateconsolidation) - Document removed models and their replacement patterns
- Map many2many table name changes
Example: In Odoo 17, account.account.code changed from Char to a stored computed field. Migration scripts must handle this type transformation at the SQL level.
Verify Field Data Types
Field type changes are common and require schema transformation.
| Version | Field | Old Type | New Type |
|---|---|---|---|
| v17+ | account.account.code | Char | Computed (stored) |
| v16+ | product.template.categ_id | Many2one | Many2many |
| v18+ | sale.order.partner_shipping_id | Many2one | Removed (use delivery fields) |
Your pre-migration script must detect these changes and apply SQL transformations.
Handle Computed Fields
Computed fields aren't populated during raw SQL migrations. You must trigger their computation manually.
Critical Fields to Recompute:
sale.order.amount_totalaccount.move.invoice_line_idsproduct.template.display_nameres.partner.commercial_partner_id
Review and Update Views
XML views reference fields and models. If either changes, views break.
View Update Checklist:
- Regenerate inherited views that override removed fields
- Update XPath expressions for restructured forms
- Test kanban, tree, and form views for each major module
- Verify search panel filters still function
Backup Everything
Before touching production, create a complete backup.
Required Backups:
- Database dump:
pg_dump -Fc odoo_db > backup.dump - Filestore: Full copy of
~/.local/share/Odoo/filestore/ - Custom modules: Version control or tar archive
- Configuration:
odoo.conffile
Test restore on a staging server before proceeding.
Post-Migration Phase
Validate Business Workflows
Test every critical business process end-to-end.
Workflow Testing:
- Sales: Quote → Order → Delivery → Invoice → Payment
- Purchase: RFQ → PO → Receipt → Vendor Bill
- Inventory: Stock moves, lot/serial tracking, valuations
- Accounting: Journal entries, reconciliation, reports
- CRM: Lead conversion, opportunity pipeline
Verify Automated Actions
Scheduled actions and server actions often reference old model names or field paths.
Check:
- Cron jobs in Settings → Technical → Automation → Scheduled Actions
- Server actions in Settings → Technical → Actions → Server Actions
- Email templates referencing renamed fields
- Automated email sending configurations
Review User Permissions
Access rights are model-specific. Model renames break permissions.
Navigate to Settings → Users & Companies → Groups. Review each group's access rights. Ensure critical users can access their modules.
Migration Script Example
Pre-migration scripts run before Odoo loads. They fix schema issues at the SQL level.
def migrate(cr, version):
# Rename model if changed
if openupgrade.table_exists(cr, 'old_model_name'):
openupgrade.rename_tables(cr, [
('old_model_name', 'new_model_name')
])
# Handle field type change (Char to Computed)
if openupgrade.column_exists(cr, 'account_account', 'code'):
cr.execute("""
ALTER TABLE account_account
ADD COLUMN code_store VARCHAR;
UPDATE account_account
SET code_store = code;
""")
# Fix many2many table names
openupgrade.rename_tables(cr, [
('product_categ_rel', 'product_template_categ_rel')
])
Common Pitfalls
Skipping Testing
Always test on a staging copy first. Production migrations without testing cause downtime and data loss.
Ignoring Custom Modules
Custom code rarely works across versions without updates. Budget time for code refactoring.
Not Recomputing Fields
Computed fields stay empty after SQL migrations. Run recompute scripts or values will be missing.
Conclusion
Database migration is both technical challenge and strategic opportunity. Done right, it modernizes your ERP infrastructure, improves performance, and unlocks new features. Done wrong, it causes data corruption and business disruption. The key is systematic planning: analyze changes, test thoroughly, backup exhaustively, and validate every workflow post-migration.
Bottom Line: Budget 2-4 weeks for a major version migration (v14 → v18). Allocate 60% to testing, 30% to code updates, 10% to execution. Never skip the staging phase.