Generate db_schema_whitelist.json file in magento 2

Posted by

This guide explores the creation and significance of db_schema_whitelist.json using the command line in Magento 2. Magento 2, a leading e-commerce platform, offers robust customization options. One essential aspect is managing the database schema, crucial for seamless operations.

The db_schema_whitelist.json file was introduced along with db_schema.xml in Magento version 2.3 and above. The purpose for db_schema.xml was to replace the existing InstallSchema and UpdateSchema classes.

Understanding db_schema_whitelist.json

Magento relies heavily on its database schema to organize and manage data efficiently. The db_schema_whitelist.json file plays a pivotal role in this context. It serves as a whitelist for database tables.

Creating via Command Line

Navigate to Magento Root Directory

cd /path/to/magento

Generate db_schema_whitelist.json

bin/magento setup:db-schema:whitelist --module-name=Vendor_Module

Replace Vendor_Module with the specific module for which you want to create the whitelist.

Verify the Changes:

The generated db_schema_whitelist.json will be located in the module’s etc directory.

Importance of db_schema_whitelist.json

  1. Enhanced Security: By explicitly specifying allowed tables, the whitelist ensures that modules can only interact with authorized parts of the database, reducing the risk of unauthorized access.
  2. Improved Performance: Controlling database access enhances performance by preventing unnecessary interactions with irrelevant tables, optimizing resource utilization.
  3. Module Isolation: Each module can have its own whitelist, promoting isolation. This is crucial for avoiding conflicts and ensuring smooth coexistence of different functionalities.
  4. Forward Compatibility: As your Magento store evolves, the whitelist allows for seamless updates and ensures that new modules don’t interfere with existing database structures.

Magento 2 utilizes the file as a mechanism to communicate which tables and columns can be securely altered through the db_schema.xml file. This file serves as a record of modifications made through various methods. Its inclusion is aimed at ensuring backward compatibility, although it is anticipated to be phased out in future versions, aligning with the eventual discontinuation of the install/upgrade script support.

In the existing transitional phase, where alterations to tables and columns can occur through setup scripts or the new etc/db_schema.xml files, Magento lacks inherent knowledge about which elements can be safely modified solely through db_schema.xml files. Thus, db_schema_whitelist.json compiles a comprehensive list of all DB tables, columns, indexes, constraints, etc., established through declarative schema. This compilation enables Magento to safely manage alterations in case changes are detected for these elements during an upgrade in the db_schema.xml file.


In conclusion, db_schema_whitelist.json is a powerful tool for controlling and securing your Magento 2 store’s database. By creating and managing this file via the command line, you gain fine-grained control over database interactions, fostering a secure and optimized e-commerce environment.