How to Generate db_schema_whitelist.json Using the Magento 2 CLI
How to Generate db_schema_whitelist.json Using the Magento 2 CLI
Learn how to generate the db_schema_whitelist.json file in Magento 2 using the CLI. This file is essential for tracking declarative schema changes in custom modules. We’ll walk through the exact command you need, where the file gets created, and why it’s important for safe database updates in Magento 2.3 and later.
Table Of Content
How to Generate db_schema_whitelist.json Using the Magento 2 CLI
In Magento 2.3 and later, the declarative schema simplifies database management by allowing you to define your module's database structure in a single XML file. To ensure Magento safely applies these schema changes, it uses a db_schema_whitelist.json file. This file records all tables, columns, and keys introduced via the declarative schema, helping Magento track and manage database changes effectively.
Generate db_schema_whitelist.json via CLI
To create the db_schema_whitelist.json file for your module, use the following command:
php bin/magento setup:db-declaration:generate-whitelist --module-name=Vendor_Module
Replace Vendor_Module with your actual module name. If you omit the --module-name option, Magento will generate whitelist files for all modules. To explicitly generate for all modules, use:
php bin/magento setup:db-declaration:generate-whitelist --module-name=all
The generated db_schema_whitelist.json file will be located in your module's etc directory:
app/code/Vendor/Module/etc/db_schema_whitelist.json
Purpose of db_schema_whitelist.json
The db_schema_whitelist.json file serves as a record of all database elements—tables, columns, indexes, and constraints—defined in your module's db_schema.xml. It helps Magento determine which database changes are safe to apply during upgrades, ensuring backward compatibility and preventing unintended alterations.
Troubleshooting Tips
If the db_schema_whitelist.json file isn't generated:
- Ensure the module is enabled: Run
php bin/magento module:enable Vendor_Module. - Clear caches: Execute
php bin/magento cache:cleanandphp bin/magento cache:flush. - Validate db_schema.xml: Check for syntax errors or issues in your
db_schema.xmlfile. - Check logs: Review
var/log/schema.logfor detailed error messages.
Summary Table
| Command | Description |
|---|---|
php bin/magento setup:db-declaration:generate-whitelist --module-name=Vendor_Module |
Generates whitelist for a specific module |
php bin/magento setup:db-declaration:generate-whitelist --module-name=all |
Generates whitelist for all modules |
php bin/magento module:enable Vendor_Module |
Enables the specified module |
php bin/magento cache:clean && php bin/magento cache:flush |
Clears Magento caches |
By following these steps, you can effectively manage your Magento 2 module's database schema using the declarative approach and ensure smooth upgrades and maintenance.
Tip
To enhance your eCommerce store’s performance with Magento, focus on optimizing site speed by utilizing Emmo themes and extensions. These tools are designed for efficiency, ensuring your website loads quickly and provides a smooth user experience. Start leveraging Emmo's powerful solutions today to boost customer satisfaction and drive sales!
FAQs
What is db_schema_whitelist.json in Magento 2?
It's a file that records all tables, columns, and keys defined by your module using Magento's declarative schema. It helps Magento track safe schema changes.
When do I need to generate db_schema_whitelist.json?
After creating or updating your db_schema.xml. The whitelist ensures Magento recognizes and applies your schema changes properly.
How do I generate the db_schema_whitelist.json file?
Run this command: php bin/magento setup:db-declaration:generate-whitelist --module-name=Vendor_Module. Replace Vendor_Module with your module’s name.
Where is the db_schema_whitelist.json file saved?
The file is saved in your module's etc directory: app/code/Vendor/Module/etc/db_schema_whitelist.json.
Can I generate the whitelist for all modules at once?
Yes. Use this command: php bin/magento setup:db-declaration:generate-whitelist --module-name=all.
What if I don’t specify the module name?
If you leave out the module name, Magento generates whitelist files for all modules by default.
What happens if the whitelist file is missing or outdated?
Magento may skip applying your schema changes or throw errors during setup. Always update it after schema changes.
Is db_schema_whitelist.json required in production?
Yes. Magento uses it to validate safe schema updates in all environments, including production.
Do I still need setup scripts with declarative schema?
No. Declarative schema replaces traditional install and upgrade scripts from Magento 2.3 onwards.
Why doesn’t my db_schema_whitelist.json file generate?
Make sure your module is enabled, your db_schema.xml is valid, and clear caches. Check var/log/schema.log for errors.
