Skip to content

unclecatvn/agent-skills / skills/odoo-18.0

odoo-18

Verified

Odoo 18 development reference for Python models and ORM (search, domain, read_group, compute fields), XML/CSV data and views, OWL/JS client code, QWeb reports, security (ACL, record rules, groups), cron and server actions, migrations and module upgrades, tests, i18n, and performance. Use this skill whenever work involves Odoo 18 or custom addons—even if the user only pastes a traceback, mentions addons/ or __manifest__.py, describes form/list/kanban/XML errors, HTTP controllers, or business rules on models—including building features, fixing bugs, refactoring, or reviewing addon code. Includes CSS/SCSS asset authoring and review for Odoo addons.

references/odoo-18-migration-guide.md

View on GitHub
---
name: odoo-18-migration
description: Comprehensive guide for upgrading modules and data to Odoo 18,
  including migration scripts, upgrade hooks, deprecations, and best practices.
globs: "**/migrations/**/*.py"
topics:
  - Migration script structure (pre/post/end)
  - Module upgrade hooks (pre_init, post_init, uninstall)
  - Deprecations and replacements
  - Data migration with SQL and ORM
  - Version checks and upgrade tooling
when_to_use:
  - Creating or reviewing migration scripts
  - Upgrading modules across major versions
  - Handling data migration and cleanup
  - Dealing with deprecations
---

# Odoo 18 Migration Guide

Comprehensive guide for migrating modules and data to Odoo 18, covering migration scripts, upgrade hooks, deprecations, and best practices.

## Table of Contents

1. [Migration Script Structure](#migration-script-structure)
2. [Module Upgrade Hooks](#module-upgrade-hooks)
3. [Migration Stages](#migration-stages)
4. [Code Upgrade Tool](#code-upgrade-tool)
5. [Deprecations in Odoo 18](#deprecations-in-odoo-18)
6. [Migration Best Practices](#migration-best-practices)
7. [Real-World Examples](#real-world-examples)
8. [Version Management](#version-management)

---

## Migration Script Structure

### Directory Layout

Migration scripts are organized in versioned directories within your module:

```python
<module>/
├── __init__.py
├── __manifest__.py
├── models/
├── migrations/
│   ├── 1.0/
│   │   ├── pre-update_table_x.py
│   │   ├── post-create_plop_records.py
│   │   └── end-cleanup.py
│   ├── 9.0.1.1/           # Server-specific version
│   ├── 16.0.1.0/          # Odoo 16.0 only
│   ├── 17.0.2.1/          # Odoo 17.0 only
│   ├── 0.0.0/             # Runs on any version change
│   └── tests/
└── upgrades/              # Alternative location
    └── 1.1/
        └── pre-migrate.py
```

### Migration Script Function Signature

```python
# File: migrations/18.0.1.0/pre-migrate_data.py

def migrate(cr, version):
    """
    Migration script for Odoo 18.0

    Args:
        cr: Database cursor (SQL operations)
        version: Previously installed version (None for new installs)
    """
    if version is None:
        return  # New installation, skip migration

    # Your migration code here
    cr.execute("""
        UPDATE your_model
        SET field_name = 'new_value'
        WHERE condition = true
    """)
```

**Valid Parameter Signatures:**
- `(cr, version)` - Recommended
- `(cr, _version)` - If version is unused
- `(_cr, version)` - If cr is unused (rare)
- `(_cr, _version)` - If both unused (rare)

### Version Format

The migration system supports these version formats:

```python
# VERSION_RE pattern from odoo/modules/migration.py
^(6.1|6.0-18.0|saas~11-99)\.?  # Optional server version prefix
\d+\.\d+(\.\d+)?              # Module version (x.y or x.y.z)

# Examples:
16.0.1.0   # Odoo 16.0, module version 1.0
17.0.2.1   # Odoo 17.0, module version 2.1
0.0.0      # Any version change
18.0       # Odoo 18.0, module version 0
```

---

## Module Upgrade Hooks

### Manifest Hooks (`__manifest__.py`)

```python
# File: __manifest__.py

{
    'name': 'My Module',
    'version': '18.0.1.0',

    # Hooks executed during module lifecycle
    'pre_init_hook': 'pre_init_function',      # Before installation
    'post_init_hook': 'post_init_function',     # After installation
    'uninstall_hook': 'uninstall_function',     # Before uninstallation
}
```

### pre_init_hook

Runs **before** the module is installed. Use for:
- Checking prerequisites
- Preparing data structures
- Validating system requirements

```python
# File: __init__.py

def pre_init_function(env):
    """Check system requirements before installation."""
    # Example: Check if required module is installed
    if not env['ir.module.module'].search([('name', '=', 'required_module')]):
        raise ValueError('Required module must be installed first')

    # Example: Create custom database tables
    env.cr.execute("""
        CREATE TABLE IF NOT EXISTS custom_table (
            id SERIAL PRIMARY KEY,
            name VARCHAR(255)
        )
    """)
```

### post_init_hook

Runs **after** the module is installed. Use for:
- Creating initial data
- Setting up configurations
- Initializing default values

```python
def post_init_function(env):
    """Initialize data after installation."""
    # Create default records
    env['my.model'].create([
        {'name': 'Default Record 1', 'code': 'DEFAULT1'},
        {'name': 'Default Record 2', 'code': 'DEFAULT2'},
    ])

    # Configure ir.config_parameter
    env['ir.config_parameter'].set_param('my_module.key', 'default_value')
```

### uninstall_hook

Runs **before** the module is uninstalled. Use for:
- Cleaning up custom tables
- Removing generated files
- Reverting system changes

```python
def uninstall_function(env):
    """Clean up before uninstallation."""
    # Drop custom tables
    env.cr.execute("DROP TABLE IF EXISTS custom_table")

    # Remove generated files
    import os
    path = os.path.join('/filestore', 'my_module')
    if os.path.exists(path):
        shutil.rmtree(path)
```

### Hook Execution Order

```
Module Upgrade Process:
├── For each module being upgraded:
│   ├── Run 'pre' migrations
│   ├── Load Python module
│   ├── Execute pre_init_hook (if new install)
│   ├── Create/update database tables
│   ├── Load data files (XML, CSV)
│   ├── Run 'post' migrations
│   └── Execute post_init_hook (if new install)
└── After all modules:
    └── Run 'end' migrations
```

---

## Migration Stages

### Pre-Stage (`pre-*.py`)

Runs **before** module initialization:
- Tables may not exist yet
- Models are not loaded
- Use raw SQL for data manipulation

```python
# File: migrations/18.0.1.0/pre-update_schema.py

def migrate(cr, version):
    """Update database schema before models are loaded."""
    # Add new column
    cr.execute("""
        ALTER TABLE your_model
        ADD COLUMN IF NOT EXISTS new_field VARCHAR(255)
    """)

    # Migrate data from old field
    cr.execute("""
        UPDATE your_model
        SET new_field = old_field
        WHERE new_field IS NULL
    """)
```

### Post-Stage (`post-*.py`)

Runs **after** module initialization:
- Tables and models are loaded
- Can use ORM (`api.Environment`)
- Best for data migrations

```python
# File: migrations/18.0.1.0/post-migrate_data.py

def migrate(cr, version):
    """Migrate data using ORM after models are loaded."""
    from odoo import api
    env = api.Environment(cr, 1, {})  # SUPERUSER_ID = 1

    # Example: Split name into first_name and last_name
    Partner = env['res.partner']
    partners = Partner.search([('name', '!=', False)])

    for partner in partners:
        names = partner.name.split(' ', 1)
        partner.write({
            'first_name': names[0],
            'last_name': names[1] if len(names) > 1 else '',
        })
```

### End-Stage (`end-*.py`)

Runs **after ALL modules have been updated:
- Can reference models from other modules
- Use for cross-module data consistency

```python
# File: migrations/18.0.1.0/end-update_references.py

def migrate(cr, version):
    """Update cross-module references after all modules loaded."""
    from odoo import api
    env = api.Environment(cr, 1, {})

    # Update references to other module's models
    sales = env['sale.order'].search([])
    for order in sales:
        # Update fields that depend on other modules
        if order.partner_id.country_id.code == 'US':
            order.write({'warehouse_id': env.ref('stock.stock_warehouse_us').id})
```

### Stage Execution Order for `0.0.0`

Version `0.0.0` scripts have special execution order:

```python
migrations/0.0.0/
├── pre-script.py  # Runs FIRST (before any other migrations)
├── post-script.py # Runs LAST (after any other migrations)
└── end-script.py  # Runs LAST among end-stage scripts
```

---

## Code Upgrade Tool

### Command-Line Usage

Odoo 18 provides a tool for automated source code transformations:

```bash
# Upgrade from one version to another
./odoo-bin upgrade_code --from 17.0 --to 18.0

# Run specific upgrade script
./odoo-bin upgrade_code --script 17.5-01-tree-to-list

# Upgrade specific addons
./odoo-bin upgrade_code --addons-path=/path/to/addons --from 17.0 --to 18.0
```

### Upgrade Script Template

```python
# File: odoo/upgrade_code/18.0-01-example.py

def upgrade(file_manager):
    """
    Upgrade script for transforming source code.

    Args:
        file_manager: Provides access to all source files
    """
    total = len(file_manager)

    for i, file in enumerate(file_manager, 1):
        # Process Python files
        if file.path.suffix == '.py':
            file.content = file.content.replace('old_pattern', 'new_pattern')

        # Process XML files
        elif file.path.suffix == '.xml':
            file.content = file.content.replace('<tree', '<list')

        # Print progress
        file_manager.print_progress(i, total)
```

### Built-in Upgrade Scripts

Located in `/Users/unclecat/dtg/odoo/odoo/upgrade_code/`:

```python
# 17.5-01-tree-to-list.py
# Converts 'tree' views to 'list' views (Odoo 17+ naming change)

def upgrade(file_manager):
    for file in file_manager:
        if file.path.suffix == '.xml':
            file.content = re.sub(
                r'(<record\s+[^>]*?)\btree\b',
                r'\1list',
                file.content
            )
```

---

## Deprecations in Odoo 18

### Manifest File Deprecation

```python
# DEPRECATED (since Odoo 17)
__openerp__.py

# Use instead
__manifest__.py
```

**Warning:**
```python
DeprecationWarning: __openerp__.py manifests are deprecated since 17.0,
rename to __manifest__.py
```

### API Method Deprecations

```python
# DEPRECATED (Odoo 18+)
records.check_access_rights(operation, raise_exception=True)
records.check_access_rule(operation)

# Use instead
records.check_access(operation)        # raises AccessError
records.has_access(operation)          # returns bool
```

### XML Declaration Deprecation

```xml
<!-- DEPRECATED (since Odoo 17) -->
<?xml version="1.0" encoding="UTF-8"?>
<odoo>
    <record model="ir.ui.view" id="view_form">
        <field name="name">my.model.form</field>
    </record>
</odoo>

<!-- XML declaration in HTML descriptions is deprecated -->
<!-- Use plain HTML without XML declaration -->
```

### Version-Specific Deprecations

```python
# Odoo 17+
# - __openerp__.py manifests
# - XML declarations in module descriptions

# Odoo 18+
# - check_access_rights() → check_access()
# - check_access_rule() → check_access()
# - _filter_access_rules() → _filtered_access()
# - _filter_access_rules_python() → _filtered_access()
```

---

## Migration Best Practices

### 1. Use Raw SQL for Performance

For large data migrations, use SQL instead of ORM:

```python
def migrate(cr, version):
    # GOOD: Fast SQL for bulk updates
    cr.execute("""
        UPDATE sale_order_line
        SET price_unit = COALESCE(
            (SELECT list_price FROM product_product
             WHERE product_product.id = sale_order_line.product_id),
            0.0
        )
    """)

    # AVOID: Slow ORM loop
    # env = api.Environment(cr, 1, {})
    # for line in env['sale.order.line'].search([]):
    #     line.price_unit = line.product_id.list_price
```

### 2. Handle NULL Version (New Installs)

```python
def migrate(cr, version):
    # Always check for new installations
    if version is None:
        return

    # Only run on upgrades from previous versions
    if parse_version(version) < parse_version('17.0.1.0'):
        # Specific migration for old versions
        pass
```

### 3. Use Environment for ORM Access

```python
from odoo import api

def migrate(cr, version):
    # Create environment with SUPERUSER_ID
    env = api.Environment(cr, 1, {})

    # Now use ORM normally
    products = env['product.product'].search([])
    for product in products:
        product.write({'default_code': product.code})
```

### 4. Batch Large Operations

```python
def migrate(cr, version):
    # Process in batches to avoid memory issues
    batch_size = 1000
    offset = 0

    while True:
        cr.execute("""
            SELECT id FROM large_table
            ORDER BY id
            LIMIT %s OFFSET %s
        """, (batch_size, offset))

        ids = [row[0] for row in cr.fetchall()]
        if not ids:
            break

        # Process batch
        cr.execute("""
            UPDATE large_table
            SET processed = true
            WHERE id = ANY(%s)
        """, (ids,))

        offset += batch_size
        cr.commit()  # Commit each batch
```

### 5. Add Rollback Protection

```python
def migrate(cr, version):
    try:
        # Migration code here
        cr.execute("ALTER TABLE model ADD COLUMN new_field VARCHAR")
    except Exception as e:
        # Log error but don't fail entire upgrade
        import logging
        logger = logging.getLogger(__name__)
        logger.warning("Migration failed: %s", e)
```

### 6. Test Migrations

```python
# File: migrations/18.0.1.0/tests/test_migration.py

from odoo.tests import TransactionCase

class TestMigration(TransactionCase):
    def test_migration(self):
        """Test that migration runs without errors."""
        # Simulate old version
        self.cr.execute("UPDATE ir_module_module SET latest_version = '17.0.1.0'")

        # Run migration
        from odoo.modules import migration
        manager = migration.MigrationManager(self.cr, 'my_module')
        manager.migrate_module(['my_module'], 'post')

        # Verify results
        self.cr.execute("SELECT COUNT(*) FROM my_model WHERE new_field IS NOT NULL")
        self.assertGreater(self.cr.fetchone()[0], 0)
```

---

## Real-World Examples

### Example 1: Field to Property Migration

```python
# File: addons/purchase/migrations/9.0.1.2/pre-create-properties.py

def migrate(cr, version):
    """Convert field to ir.property for multi-company support."""

    def convert_field(cr, model, field, target_model):
        # Get existing values
        cr.execute("""
            SELECT id, {field}, company_id
            FROM {table}
            WHERE {field} IS NOT NULL
        """.format(field=field, table=model.replace('.', '_')))

        # Insert as properties
        for record_id, value, company_id in cr.fetchall():
            cr.execute("""
                INSERT INTO ir_property (
                    name, type, fields_id,
                    company_id, value_reference, res_id
                )
                VALUES (
                    %s, 'many2one',
                    (SELECT id FROM ir_model_fields
                     WHERE model = %s AND name = %s),
                    %s, %s, %s
                )
            """, (field, model, field, company_id,
                  f'{target_model},{value}', f'{model},{record_id}'))

        # Drop old column
        cr.execute(f'ALTER TABLE "{model.replace(".", "_")}" DROP COLUMN "{field}"')

    convert_field(cr, 'purchase.order', 'warehouse_id', 'stock.warehouse')
```

### Example 2: UUID Deduplication

```python
# File: addons/point_of_sale/upgrades/1.0.2/post-deduplicate-uuids.py

def migrate(cr, version):
    """Fix duplicate UUIDs from upgrade."""

    def deduplicate_uuids(table):
        # Find duplicates
        cr.execute(f"""
            SELECT UNNEST(ARRAY_AGG(id))
            FROM {table}
            WHERE uuid IS NOT NULL
            GROUP BY uuid
            HAVING COUNT(*) > 1
        """)

        for record_ids in cr.fetchall():
            # Keep first, regenerate rest
            record_ids = list(record_ids)
            for record_id in record_ids[1:]:
                cr.execute(f"""
                    UPDATE {table}
                    SET uuid = gen_random_uuid()
                    WHERE id = %s
                """, (record_id,))

    deduplicate_uuids('pos_order')
    deduplicate_uuids('pos_order_line')
```

### Example 3: Tag Migration with SQL

```python
# File: addons/l10n_nl/migrations/3.3/post-migrate_update_taxes.py

def migrate(cr, version):
    """Update tax tags with SQL for performance."""
    from odoo.tools import SQL

    env = api.Environment(cr, 1, {})

    # Find old and new tags
    old_tag = env.ref('l10n_nl.tax_tag_old', raise_if_not_found=False)
    new_tag = env.ref('l10n_nl.tax_tag_new', raise_if_not_found=False)

    if old_tag and new_tag:
        # Use SQL for bulk update
        cr.execute(SQL("""
            UPDATE account_account_tag_account_tax_repartition_line_rel
            SET account_account_tag_id = %(new_tag)s
            WHERE account_account_tag_id = %(old_tag)s
        """), {'old_tag': old_tag.id, 'new_tag': new_tag.id}))
```

### Example 4: Currency Migration

```python
# File: migrations/18.0.1.0/post-migrate_currency.py

def migrate(cr, version):
    """Migrate to multi-currency support."""
    from odoo import api

    env = api.Environment(cr, 1, {})

    # Get company currency
    company = env['res.company'].search([], limit=1)
    currency_id = company.currency_id.id

    # Add currency field to existing records
    cr.execute("""
        UPDATE sale_order
        SET currency_id = %s
        WHERE currency_id IS NULL
    """, (currency_id,))

    # Update pricelist currency
    cr.execute("""
        UPDATE product_pricelist
        SET currency_id = %s
        WHERE currency_id IS NULL
    """, (currency_id,))
```

### Example 5: Many2many Relationship Migration

```python
# File: migrations/18.0.1.0/post-migrate_m2m.py

def migrate(cr, version):
    """Migrate Many2many relationship to new model."""
    from odoo import api

    env = api.Environment(cr, 1, {})

    # Create new relationship records
    cr.execute("""
        INSERT INTO model1_model2_rel (model1_id, model2_id)
        SELECT m1.id, m2.id
        FROM old_table ot
        JOIN model1 m1 ON ot.old_field1 = m1.old_id
        JOIN model2 m2 ON ot.old_field2 = m2.old_id
        ON CONFLICT DO NOTHING
    """)

    # Drop old table
    cr.execute("DROP TABLE IF EXISTS old_table")
```

---

## Version Management

### Version Parsing

```python
from odoo.tools.parse_version import parse_version

# Parse versions for comparison
v1 = parse_version('17.0.1.0')
v2 = parse_version('18.0.0.1')

if v2 > v1:
    print("v2 is newer")

# Supports semantic versioning
parse_version('18.0.1.0.alpha')  # Pre-release
parse_version('18.0.1.0.beta1')   # Beta
parse_version('18.0.1.0.rc2')     # Release candidate
```

### Version Adaptation

```python
# From odoo/modules/module.py
def adapt_version(version):
    """Adapts module version to current Odoo series."""
    serie = release.major_version  # e.g., "18.0"

    if version == serie or not version.startswith(serie + '.'):
        version = f'{serie}.{version}'

    # Validates format: x.y or x.y.z or serie.x.y or serie.x.y.z
    return version

# Examples:
adapt_version('1.0')      # → '18.0.1.0'
adapt_version('18.0.1.0') # → '18.0.1.0'
```

### Version-Specific Migrations

```python
def migrate(cr, version):
    """Handle migration from multiple previous versions."""

    if version is None:
        return  # New installation

    parsed_version = parse_version(version)

    # Migrate from 16.0
    if parsed_version < parse_version('17.0'):
        cr.execute("UPDATE model SET field = 'v16_value'")

    # Migrate from 17.0
    if parsed_version < parse_version('18.0'):
        cr.execute("UPDATE model SET field = 'v17_value'")

    # Migrate to 18.0
    cr.execute("UPDATE model SET field = 'v18_value'")
```

---

## Additional Resources

### Key Files Reference

| File Path | Purpose |
|-----------|---------|
| `/odoo/modules/migration.py` | Core migration system |
| `/odoo/modules/loading.py` | Module loading & upgrade orchestration |
| `/odoo/modules/module.py` | Module discovery & version management |
| `/odoo/modules/registry.py` | Model registry management |
| `/odoo/cli/upgrade_code.py` | Source code upgrade tool |
| `/odoo/tools/parse_version.py` | Version parsing utilities |
| `/addons/base/models/ir_module.py` | Module model & operations |
| `/odoo/upgrade_code/` | Automated upgrade scripts |

### Testing Migrations

```python
# Test migration with upgrade
python odoo-bin -d test_db --init=your_module --test-enable

# Test specific migration
python odoo-bin -d test_db --update=your_module --test-enable
```

### Debug Mode

```bash
# Enable logging for migration debugging
./odoo-bin --log-level=debug --log-handler=odoo.modules.migration:DEBUG
```

### Quick Reference

```python
# Migration script template
def migrate(cr, version):
    """
    Odoo 18 Migration Script

    Args:
        cr: Database cursor
        version: Previously installed version
    """
    # Check for new install
    if version is None:
        return

    # Migration code here
    pass
```
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall