Step-by-Step Guide to Fixing Database Errors During Mautic 5.2.5 to 6.0.0 Upgrades

4 min read

Mautic upgrades often involve database schema changes to support new features or improvements. However, migrations may fail due to:

  • Schema discrepancies (e.g., missing columns from prior updates).
  • Customisations or third-party plugins interfering with migrations.
  • Version-specific bugs in migration scripts.

This guide addresses two critical issues encountered when upgrading from v5.2.1 to 6.0.0

  1. A missing is_read_only column in the form_fields table during the 5.2.1 → 5.2.5 upgrade.
  2. A database constraint violation (mautic_emails.headers) during the 5.2.5 → 6.0.0 upgrade, caused by missing uuid fields in multiple tables.

By following these steps, you’ll resolve schema inconsistencies and ensure a smooth migration.

Step-by-Step Guide to Migrating Mautic

Step 1: Upgrade from 5.2.1 to 5.2.5

The following should be run directly after the upgrade, ensure you check the database if the table has the missing field.

  1. Run the Migration Command
    Execute the following command to apply pending migrations:

    php bin/console doctrine:migrations:migrate "Mautic\Migrations\Version20241227065658" --env=prod

    This adds the missing is_read_only column to the form_fields table.

    Alternative Manual Fix:
    If the migration fails, manually add the column via SQL:

    ALTER TABLE form_fields ADD COLUMN is_read_only TINYINT(1) DEFAULT 0;

Step 2: Upgrade from 5.2.5 to 6.0.0

  1. Run the Migration Command
    Attempt the standard migration:

    php bin/console doctrine:migrations:migrate --env=prod

  2. Resolve Integrity Constraint Violation
    If you encounter the error:

    SQLSTATE[23000]: Integrity constraint violation: 4025 CONSTRAINT `mautic_emails.headers`

    This indicates missing uuid columns in critical tables.

  3. Add Missing uuid Columns
    Execute these SQL commands to add the uuid field to affected tables (remember to change the database prefix):

    ALTER TABLE mautic_assets ADD COLUMN `uuid` char(36) DEFAULT NULL;  
ALTER TABLE mautic_campaigns ADD COLUMN `uuid` char(36) DEFAULT NULL;  
ALTER TABLE mautic_campaign_events ADD COLUMN `uuid` char(36) DEFAULT NULL;  
ALTER TABLE mautic_categories ADD COLUMN `uuid` char(36) DEFAULT NULL;  
ALTER TABLE mautic_dynamic_content ADD COLUMN `uuid` char(36) DEFAULT NULL;  
ALTER TABLE mautic_emails ADD COLUMN `uuid` char(36) DEFAULT NULL;  
ALTER TABLE mautic_focus ADD COLUMN `uuid` char(36) DEFAULT NULL;  
ALTER TABLE mautic_forms ADD COLUMN `uuid` char(36) DEFAULT NULL;  
ALTER TABLE mautic_form_actions ADD COLUMN `uuid` char(36) DEFAULT NULL;  
ALTER TABLE mautic_form_fields ADD COLUMN `uuid` char(36) DEFAULT NULL;  
ALTER TABLE mautic_lead_fields ADD COLUMN `uuid` char(36) DEFAULT NULL;  
ALTER TABLE mautic_lead_lists ADD COLUMN `uuid` char(36) DEFAULT NULL;  
ALTER TABLE mautic_lead_tags ADD COLUMN `uuid` char(36) DEFAULT NULL;  
ALTER TABLE mautic_messages ADD COLUMN `uuid` char(36) DEFAULT NULL;  
ALTER TABLE mautic_message_channels ADD COLUMN `uuid` char(36) DEFAULT NULL;  
ALTER TABLE mautic_monitoring ADD COLUMN `uuid` char(36) DEFAULT NULL;  
ALTER TABLE mautic_pages ADD COLUMN `uuid` char(36) DEFAULT NULL;  
ALTER TABLE mautic_permissions ADD COLUMN `uuid` char(36) DEFAULT NULL;  
ALTER TABLE mautic_points ADD COLUMN `uuid` char(36) DEFAULT NULL;  
ALTER TABLE mautic_point_trigger_events ADD COLUMN `uuid` char(36) DEFAULT NULL;  
ALTER TABLE mautic_point_triggers ADD COLUMN `uuid` char(36) DEFAULT NULL;  
ALTER TABLE mautic_push_notifications ADD COLUMN `uuid` char(36) DEFAULT NULL;  
ALTER TABLE mautic_reports ADD COLUMN `uuid` char(36) DEFAULT NULL;  
ALTER TABLE mautic_roles ADD COLUMN `uuid` char(36) DEFAULT NULL;  
ALTER TABLE mautic_sms_messages ADD COLUMN `uuid` char(36) DEFAULT NULL;  
ALTER TABLE mautic_stages ADD COLUMN `uuid` char(36) DEFAULT NULL;

  4. Finalise the Migration
    After adding the columns, re-run the migration command:

    php bin/console doctrine:migrations:migrate --env=prod

Further notes

  1. Backup First: Always take a full database backup before performing schema changes.
  2. UUID Generation: After adding uuid fields, Mautic may auto-populate them. Verify data integrity post-migration.
  3. Ongoing discussion: click here.
  4. Schema Consistency: Compare your database schema with a fresh 6.0.0 installation to identify discrepancies.

Related post