Magento 2: How to Create db_schema_whitelist.json

Magento 2 introduced the Declarative Schema approach starting from version 2.3. This allows developers to define database structures (tables, columns, indexes, constraints) in XML files instead of writing install/upgrade scripts. One important part of this system is the db_schema_whitelist.json file, which helps Magento track and validate schema changes.

What is db_schema_whitelist.json?

The db_schema_whitelist.json file is automatically generated by Magento when you use the declarative schema. It contains a list of tables and columns that Magento recognizes as part of the schema. This file ensures that:

• Magento knows which columns are safe to modify.
• Schema changes are tracked consistently.
• Developers avoid accidental drops or overwrites of important database structures.

When Do You Need It?

You need to generate db_schema_whitelist.json whenever:

• You add new tables or columns via db_schema.xml.
• You modify existing schema definitions.
• You upgrade Magento and want to ensure schema consistency.

Step 1: Define Schema in db_schema.xml

Inside your module, create or update etc/db_schema.xml with your table definition:

<?xml version="1.0"?>
<schema xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:Setup/Declaration/Schema/etc/schema.xsd">

    <table name="vendor_module_example" resource="default" engine="innodb">
        <column xsi:type="int" name="entity_id" nullable="false" identity="true" unsigned="true" comment="Entity ID"/>
        <column xsi:type="varchar" name="title" nullable="false" length="255" comment="Title"/>
        <constraint xsi:type="primary" referenceId="PRIMARY">
            <column name="entity_id"/>
        </constraint>
    </table>

</schema>

Step 2: Generate db_schema_whitelist.json

Run the following command from your Magento root directory:

bin/magento setup:db-declaration:generate-whitelist

This command scans your db_schema.xml and generates db_schema_whitelist.json in your module’s etc directory.

Step 3: Verify the File

The generated db_schema_whitelist.json will look something like this:

{
    "vendor_module_example": {
        "column": {
            "entity_id": true,
            "title": true
        }
    }
}

This confirms that Magento recognizes the columns and will not drop them during future upgrades.

Step 4: Commit to Version Control

Always commit db_schema_whitelist.json to your repository along with db_schema.xml. This ensures consistency across environments (local, staging, production).

Troubleshooting

• If the file is not generated, check that your db_schema.xml is valid and follows the schema definition rules.
• Run bin/magento setup:upgrade after generating the whitelist to apply changes.
• Ensure your module is enabled (bin/magento module:enable Vendor_Module).

Best Practices

• Always regenerate db_schema_whitelist.json after modifying db_schema.xml.
• Do not edit db_schema_whitelist.json manually — let Magento generate it.
• Use declarative schema for new modules instead of legacy install/upgrade scripts.
• Test schema changes in a staging environment before deploying to production.

Conclusion

The db_schema_whitelist.json file is a critical part of Magento’s declarative schema system. It ensures safe and consistent database changes across environments. By defining your schema in db_schema.xml and generating the whitelist file, you can avoid common issues with missing tables or dropped columns during upgrades.

Happy Coding & Schema Managing!