What is the use of db_schema_whitelist.json located in Magento Catalog etc directory?

In Magento 2.3 version, I found db_schema_whitelist.json and db_schema.xml files, in the Magento_Catalog module.

Having idea about db_schema.xml, that is related with declarative schema management.

Also found that db_schema_whitelist.json file located in etc directory and it contains GraphQL based attributes that may be require to fetch attributes at frontend.

I want to know that which operations Magento 2 application will consider for db_schema_whitelist.json for Magento_Catalog in terms of GraphQL.

3 Answers 3


The db_schema_whitelist.json file is a way of telling Magento which tables and columns it can safely alter using the db_schema.xml file. It was added to preserve backward compatibility and will be removed in a future version when the install/upgrade script be no longer supported.

In the current dual state where tables and columns can be added/altered/removed either via setup scripts (those located in the Setup folder) or via the new etc/db_schema.xml files, Magento can not know by itself which tables/columns can be safely altered using only the db_schema.xml files. Hence, the db_schema_whitelist.json holds a list of all the DB tables, columns, indexes, constraints, etc that where created via declarative schema and can therefore be safely altered in case it detects any change for those elements in an upgraded db_schema.xml file. Hope it makes more sense now.


db_schema_whitelist.json file provides a history of all tables, columns, keys added with declarative schema. It can be generated manually or created automatically with the following command :

php bin/magento setup:db-declaration:generate-whitelist --module-name=RH_Helloworld

RH_Helloworld is module name.

If no module name is specified, then the default behavior is to generate a whitelist for all modules. You can also explicitly set --module-name=all.



Magento 2 versions from 2.3 have a replacement for traditional install/upgrade schema which is used to maintain the database structure.

From Magento 2 version 2.3, they have introduced the declarative schema file for database (etc/db_schema.xml) which is used to maintain the database structure for a module.

Now you can forget about untidy install/upgrade file and see the latest database structure version of a module in a single file.

For Magento 2 to identify the database schema changes, you need to maintain a file db_schema_whitelist.json against which Magento will compare your database structure from db_schema.xml and decide to update the database structure of your module while executing bin/magento setup:upgrade command.

In order to create the db_schema_whitelist.json in your Magento 2 module, you can run the below command:

php bin/magento setup:db-declaration:generate-whitelist [options]

Where [options] will be,


specifies the Module name to generate a whitelist.

Official Magento 2 documentation:



Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.