Moving Beyond Upgrade Scripts: Implementing Magento 2 Declarative Schema

The Friction of Procedural Database Updates

In older versions of Magento 2, changing a database table required writing procedural PHP scripts in UpgradeSchema.php. You had to manually track which version of the module the database was currently on, write the specific ALTER TABLE logic for that version jump, and hope that your teammates didn't introduce a conflicting change in a parallel branch.

This approach is fragile. If a developer misses a version step or if two developers modify the same table in different ways, the database state becomes inconsistent across environments. The core problem is that procedural scripts describe how to change the database, rather than what the database should look like.

The Declarative Approach

Declarative schema, introduced in Magento 2.3, shifts the logic from PHP scripts to an XML configuration file: db_schema.xml. Instead of writing a sequence of steps to reach a goal, you define the final desired state of your tables, columns, and indexes. Magento then compares this declaration against the actual state of the database and automatically generates the necessary SQL to align them.

This eliminates the need for InstallSchema and UpgradeSchema files for structural changes. When you run the upgrade command, Magento computes the delta and applies only the missing pieces.

Worked Example: Adding a Product Attribute Column

Suppose you need to add a sku_suffix column to the catalog_product_entity table to support a new internal labeling system. Instead of writing a PHP class, you define this in your module's configuration.

1. Define the Schema

Create or edit app/code/Vendor/Module/etc/db_schema.xml:

<schema xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Setup/Declaration/Schema/etc/db_schema.xsd">
    <table name="catalog_product_entity">
        <column xsi:type="varchar" name="sku_suffix" nullable="true" length="255" comment="Internal SKU Suffix" />
    </table>
</schema>

2. Apply the Change

Run the following command from the Magento root directory. This requires shell access with permissions to execute PHP and write to the database.

bin/magento setup:upgrade

Expected Result: Magento will detect the new column definition in the XML, compare it to the existing catalog_product_entity table, and execute an ALTER TABLE statement. You should see a confirmation that the schema was updated in the console output.

3. Verification

To verify the change, log into your database client (e.g., MySQL CLI) and run:

DESCRIBE catalog_product_entity;

Check for the presence of the sku_suffix column with the correct type and nullability.

Managing Schema Drift and Whitelists

One risk of declarative schema is that Magento might attempt to drop columns or tables that exist in the database but are not declared in any db_schema.xml file. To prevent accidental data loss, Magento uses a whitelist mechanism.

To ensure your module's changes are tracked and that other undocumented tables are preserved, generate a whitelist for your specific module:

bin/magento setup:db-schema:declare --whitelisted-modules=Vendor_Module

This creates a db_schema_whitelist.json file. This file should be committed to version control; it tells Magento which tables and columns are "known" and should not be dropped during the synchronization process.

Limitations and Trade-offs

While declarative schema simplifies structure, it does not handle data migration. If you need to populate the new sku_suffix column based on existing data in another table, db_schema.xml cannot do this. You must still use DataPatch classes for data transformation tasks.

Additionally, complex operations—such as renaming a column—can be ambiguous to the declarative engine. Magento might interpret a rename as "drop old column, add new column," which would result in total data loss for that field. In these specific cases, manual SQL or custom migration logic is required.

Actionable Summary

When modifying database structures in Magento 2.3+, avoid PHP upgrade scripts. Define your tables and columns in db_schema.xml, run setup:upgrade, and immediately generate your db_schema_whitelist.json to protect your data. For any logic involving the movement or transformation of existing records, implement a DataPatch.