Odoo Migration: Handling Custom Fields and Database Column Mappings

Direct Approach to Odoo Custom Field and Column Mapping

Handling custom fields and database column mappings in Odoo migrations requires a rigorous, manual verification process rather than relying on automatic schema conversion. The recommended approach involves a three-phase strategy: comprehensive schema profiling of the source database, detailed mapping of custom fields to target version models, and extensive validation in a representative staging environment. This process is critical because Odoo version upgrades often introduce changes to the Object-Relational Mapping (ORM) layer, model inheritance structures, and field type definitions that can silently corrupt data or break custom modules if not addressed. The primary risks to control include data loss due to type mismatches, broken foreign key relationships, and functional failures in custom business logic that depends on specific column structures. By treating database schema changes as a first-class component of the migration plan, organizations can protect business data integrity and ensure operational continuity during the transition.

Phase 1: Source Database Profiling and Inventory

Before initiating any migration steps, the technical team must create a complete inventory of the current database schema. This involves querying the PostgreSQL database to identify all tables, columns, indexes, and constraints associated with Odoo models. Special attention must be paid to custom fields added via custom modules, as these are not part of the standard Odoo schema and are therefore not automatically managed by the core upgrade scripts. The team should document the data type, length, nullability, and default values for each custom column. Additionally, identify any custom SQL views, stored procedures, or triggers that interact with these columns, as these may need to be rewritten or removed depending on the target version's compatibility. This inventory serves as the baseline for all subsequent mapping and validation activities.

Identifying Custom vs. Standard Fields

Distinguishing between standard Odoo fields and custom fields is essential. Standard fields are defined in the official Odoo modules and are typically handled by the upgrade framework. Custom fields, however, are defined in third-party or in-house modules. To identify these, compare the database schema against the schema of a clean installation of the same source version. Any discrepancies represent custom modifications. This comparison helps isolate the specific columns that require manual mapping and validation. It also highlights any custom indexes or constraints that may need to be recreated in the target environment.

Phase 2: Mapping Custom Fields to Target Schema

Once the source inventory is complete, the next step is to map each custom field to its corresponding location in the target Odoo version. This involves reviewing the target version's model definitions to determine if the custom field still exists, has been renamed, or has been replaced by a new standard field. If the field has been removed or deprecated in the target version, a decision must be made to either migrate the data to a new custom field, archive the data, or discard it. This decision requires input from business stakeholders to ensure that no critical business data is lost. For fields that remain, verify that the data types are compatible. For example, if a field was changed from a character type to a text type, ensure that the data can be safely cast without truncation or encoding errors.

Handling Type Changes and Deprecations

Odoo upgrades may change the underlying data types of fields or deprecate certain field types entirely. For instance, older versions may use specific integer types that are replaced by more generic types in newer versions. The migration plan must include explicit transformation rules for these changes. If a field type is deprecated, the custom module code must be updated to use the new type, and the database column must be altered accordingly. This process should be documented in a migration runbook to ensure consistency and auditability. It is crucial to verify these changes against the official Odoo release notes for the specific source and target versions, as compatibility details can vary significantly between releases.

Phase 3: Staging Environment Validation

The most critical phase of the migration is validation in a staging environment that mirrors the production database. Load a representative sample of production data into the staging environment and execute the migration scripts. After the migration, run a series of automated and manual checks to verify data integrity. These checks should include row count comparisons, checksum validations for critical tables, and functional tests of custom modules that depend on the migrated fields. Any discrepancies must be investigated and resolved before proceeding to production. This phase allows the team to identify and fix issues in a controlled environment, minimizing the risk of data loss or downtime in production.

Automated Data Reconciliation