Generate db_schema_whitelist.json Using Magento 2 CLI
Generate db_schema_whitelist.json Using Magento 2 CLI
Use the Magento 2 CLI to generate the db_schema_whitelist.json file for your module. This file tracks all database tables, columns, and keys defined through db_schema.xml. It's essential for Magento to apply and manage schema changes safely, especially after updates.
Table Of Content
Generate db_schema_whitelist.json Using Magento 2 CLI
To create the db_schema_whitelist.json file in Magento 2, use the command line interface (CLI). This file is essential for tracking database schema changes introduced via the declarative schema approach.
What Is db_schema_whitelist.json?<
Introduced in Magento 2.3, the db_schema_whitelist.json file records all tables, columns, and keys added through the declarative schema. It helps Magento identify which database elements can be safely modified using db_schema.xml. This mechanism ensures backward compatibility and stability during database upgrades.
How to Generate db_schema_whitelist.json Using CLI
Navigate to your Magento root directory and execute the following command:
php bin/magento setup:db-declaration:generate-whitelist --module-name=Vendor_Module
php bin/magento setup:db-declaration:generate-whitelist --module-name=Vendor_Module
Replace Vendor_Module with your specific module's name. This command generates the db_schema_whitelist.json file in the etc directory of your module.
To generate whitelist files for all modules, use:
php bin/magento setup:db-declaration:generate-whitelist --module-name=all
Troubleshooting Tips
- Module Not Enabled: Ensure your module is enabled before generating the whitelist.
- Cache Issues: Clear the cache to avoid conflicts.
- Check for Errors: If the file isn't generated, inspect
var/log/schema.log for errors in yourdb_schema.xml.
php bin/magento module:enable Vendor_Module
php bin/magento cache:clean
Summary Table
| Task | Command |
|---|---|
| Generate whitelist for a specific module | php bin/magento setup:db-declaration:generate-whitelist --module-name=Vendor_Module |
| Generate whitelist for all modules | php bin/magento setup:db-declaration:generate-whitelist --module-name=all |
| Enable a module | php bin/magento module:enable Vendor_Module |
| Clear cache | php bin/magento cache:clean |
By following these steps, you can effectively manage your Magento 2 database schema using the db_schema_whitelist.json file.
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 lists all tables, columns, and keys your module defines with db_schema.xml. Magento uses it to safely track schema changes.
Why do I need to generate db_schema_whitelist.json?
Magento won’t apply your database changes correctly without it. It’s required after modifying db_schema.xml.
How do I generate the db_schema_whitelist.json file?
Run this in the terminal: php bin/magento setup:db-declaration:generate-whitelist --module-name=Vendor_Module. Replace Vendor_Module with your actual module name.
Where is db_schema_whitelist.json saved?
It’s saved in your module’s etc directory. Example path: app/code/Vendor/Module/etc/db_schema_whitelist.json.
Can I generate the whitelist for all modules at once?
Yes. Run php bin/magento setup:db-declaration:generate-whitelist --module-name=all to cover every module.
What if I don’t specify a module name?
Magento will create whitelist files for all modules by default if you skip the module name.
What happens if the file is missing or outdated?
Magento might ignore your schema updates or throw setup errors. Always regenerate it after schema changes.
Is db_schema_whitelist.json needed in production?
Yes. Magento relies on it in every environment to safely manage schema changes, including production.
Do I still need install or upgrade scripts?
No. Starting with Magento 2.3, declarative schema replaces the old setup scripts.
Why isn't my whitelist file generating?
Check if your module is enabled. Validate your db_schema.xml and clear cache. Look in var/log/schema.log for issues.
