Connected business operations. Flexible deployment.
A practical guide for CIOs and ERP consultants on handling custom fields, database schema changes, and data integrity during Odoo version upgrades. Learn how to assess risks, map dependencies, and ensure operational continuity.
Managing custom fields and database columns during an Odoo migration requires a structured approach to schema mapping, dependency analysis, and data validation. The primary risk is data loss or corruption when the Object-Relational Mapping (ORM) layer changes between versions, causing custom fields to become orphaned or incompatible. To mitigate this, organizations must perform a detailed audit of all custom modules, map each custom field to its corresponding database column, and verify compatibility against the target version's official documentation. This process ensures that business-critical data remains intact and that custom functionality continues to operate without manual intervention or data loss. The recommended approach involves creating a comprehensive inventory of customizations, testing the upgrade in a representative staging environment, and implementing strict reconciliation checks before cutover.
The first step in any Odoo migration is to clearly define the source and target versions. Odoo releases new major versions annually, and each version may introduce breaking changes to the ORM, database schema, or API. It is critical to verify whether the target version is supported by the vendor and whether the specific combination of source and target versions is officially supported for direct upgrades. For example, upgrading from Odoo 14 to Odoo 17 may require intermediate steps or specific migration scripts provided by the vendor. Always consult the official Odoo documentation for the exact versions involved to confirm compatibility and identify any known issues. This assessment should include a review of the vendor's support lifecycle to ensure that the target version will receive security updates and bug fixes for the desired duration.
During the compatibility assessment, identify any deprecated features, APIs, or models that are used by custom modules. Odoo frequently deprecates certain methods or fields in favor of new implementations. If a custom module relies on a deprecated API, it may fail to load or behave unexpectedly in the target version. Create a list of all deprecated elements used in your custom code and plan for refactoring or replacement. This step is crucial for preventing runtime errors and ensuring that custom functionality remains stable after the upgrade.
A thorough audit of custom fields and database columns is essential for a successful migration. Custom fields in Odoo are defined in Python models and mapped to database columns in PostgreSQL. When upgrading, the ORM may change how fields are stored, indexed, or related to other models. You must create a detailed inventory of all custom fields, including their data types, constraints, and relationships. This inventory should also include any custom database columns that were added manually or through third-party modules. Use database introspection tools to extract the current schema and compare it with the expected schema of the target version. This comparison will reveal any discrepancies that need to be addressed before the upgrade.
Custom fields often depend on other fields or models through inheritance or relationships. For example, a custom field on a sales order line may depend on a field on the product model. If the product model changes in the target version, the custom field may break. Map all field dependencies and inheritance chains to identify potential points of failure. This mapping should include both direct dependencies (e.g., field A depends on field B) and indirect dependencies (e.g., field A depends on a model that depends on field B). Use this map to prioritize testing and refactoring efforts.
A representative staging environment is critical for testing the migration. The staging environment should mirror the production environment in terms of data volume, custom modules, and integrations. Load a copy of the production database into the staging environment and apply the upgrade scripts. This allows you to test the upgrade process, identify errors, and validate data integrity without risking production data. Ensure that the staging environment has the same hardware and software configuration as production to avoid performance discrepancies. Use the staging environment to run automated tests, manual tests, and user acceptance tests (UAT) to verify that all custom functionality works as expected.
Automated tests are essential for verifying that custom modules and fields work correctly after the upgrade. Write unit tests for each custom module to verify that fields are created, updated, and deleted as expected. Run integration tests to verify that custom fields interact correctly with other modules and integrations. Manual tests should focus on business processes that use custom fields, such as creating a sales order with custom fields or generating a report that includes custom data. Use the results of these tests to identify and fix any issues before proceeding to production.
The database migration is the most critical step in the Odoo upgrade process. It involves applying schema changes, migrating data, and updating the ORM registry. Use the official Odoo upgrade scripts to apply schema changes and migrate data. These scripts are designed to handle common migration scenarios, but they may not cover all custom fields or database columns. Review the upgrade scripts carefully and make any necessary modifications to handle custom fields. Always take a full backup of the production database before running the upgrade scripts. This backup should be tested for restore to ensure that it is valid and complete.
Custom database columns that are not managed by the ORM may require manual migration. These columns may have been added through SQL scripts or third-party tools. Identify all custom database columns and determine how they should be migrated to the target version. Some columns may need to be renamed, dropped, or converted to a different data type. Use SQL scripts to perform these migrations and verify that the data is intact after the migration. Document all manual migrations to ensure that they can be repeated if necessary.
After the database migration, validate data integrity and perform reconciliation checks. Compare the number of records in key tables before and after the migration to ensure that no data was lost. Verify that custom fields contain the correct data by sampling records and comparing them with the pre-migration data. Use reconciliation reports to verify that financial data, such as balances and transactions, is consistent before and after the migration. Any discrepancies should be investigated and resolved before proceeding to production. This step is crucial for ensuring that the migration does not introduce data errors that could impact business operations.
Cutover planning is essential for minimizing downtime and ensuring a smooth transition to the new version. Define a cutover window that allows enough time to complete the migration, validate data, and perform final checks. Establish go/no-go criteria based on the results of testing and validation. If any critical issues are identified, do not proceed with the cutover. Have a rollback plan in place in case the migration fails or introduces critical issues. The rollback plan should include steps to restore the pre-migration backup and revert any changes made to the production environment. Test the rollback plan in the staging environment to ensure that it works as expected.
Communicate the cutover plan and timeline with all stakeholders, including IT, finance, operations, and end users. Provide clear instructions on what to expect during the cutover window and how to report any issues. Establish a communication channel for real-time updates during the cutover. This helps to manage expectations and ensure that everyone is prepared for the transition. After the cutover, provide a summary of the migration results and any issues that were encountered.
After the migration is complete, monitor the system closely for any issues. Check logs for errors or warnings that may indicate problems with custom modules or fields. Monitor performance to ensure that the system is operating within expected parameters. Address any issues that arise promptly to prevent them from impacting business operations. Provide support to end users who may encounter issues with custom fields or functionality. Use the first few weeks after the migration to identify and fix any remaining issues and to optimize the system for performance and usability.
| Phase | Key Activities | Responsible Role | Success Criteria |
|---|---|---|---|
| Assessment | Version compatibility check, custom field audit | ERP Consultant | Compatibility report approved |
| Preparation | Staging environment setup, test plan creation | IT Director | Staging environment ready |
| Execution | Database migration, schema updates | DBA | Migration completed without errors |
| Validation | Data reconciliation, UAT | QA Team | All tests passed |
| Cutover | Production upgrade, rollback plan | Project Manager | System live with no critical issues |
Common questions on this topic. Talk to our team for anything specific to your business.
Custom fields are typically preserved if they are defined in custom modules that are compatible with the target version. However, if the ORM or model structure changes, custom fields may need to be refactored or redefined. Always test custom fields in a staging environment before upgrading production.
Review the module's code for deprecated APIs or models. Check the vendor's documentation for compatibility notes. Test the module in a staging environment with the target version to identify any issues.
Yes, but you must manually map and migrate any custom database columns that are not managed by the ORM. Use SQL scripts to ensure that these columns are correctly transferred to the target version.
Use a representative staging environment with a copy of the production database. Run automated and manual tests to verify that all custom functionality works as expected. Perform data reconciliation to ensure data integrity.
The duration depends on the complexity of the customizations, the size of the database, and the number of integrations. A simple upgrade may take a few hours, while a complex migration with many custom modules may take several days.
The main risks are data loss, corruption, and inability to rollback if the upgrade fails. Always take a full backup of the production database before starting the upgrade and test the backup for restore.
A practical guide for IT leaders and ERP consultants to identify, diagnose, and resolve common data migration errors, ensuring data integrity and operational continuity during ERP upgrades or replacements.
Learn how to design retail ERP architectures that unify inventory visibility and procurement governance, enabling scalable operations without sacrificing control.
A practical guide for CIOs and IT leaders on structuring employee training and change management to ensure successful ERP migration adoption, reduce resistance, and maintain operational continuity.
Discuss your workflows, modules and deployment options with our team.
Back to resources