After Adobe Commerce and Magento Open Source 2.3, the declarative schema file for database (etc/db_schema.xml) is used to maintain the database structure for a module in  a single file.

What is db_schema_whitelist.json file

Lets see db_schema_whitelist.json file,

1. 1. db_schema_whitelist.json file is a history of all tables, columns, and keys added with the declarative schema.
   2. 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.
   3. It was added to preserve backward compatibility and will be removed in a future version when the install/upgrade script be no longer supported.

Why db_schema_whitelist.json file is added in Magento2?

In the current scenario, tables and columns can be added/altered/removed using below two methods

• • setup scripts (those located in the Setup folder) or
  • etc/db_schema.xml files

So, to distinguish between which tables/columns can be safely altered using only the db_schema.xml files, db_schema_whitelist.json file has been introduced or added.

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.

Also It was added to preserve backward compatibility and will be removed in a future version when the install/upgrade script be no longer supported.

How to create db_schema_whitelist.json in Magento 2:

To create db_schema_whitelist.json, first you need to create db_schema.xml file. Lets assume that we have following file with below content in app/code/Vendorname/Modulename/etc/db_schema.xml

Example:

<?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="mytablename" resource="default" comment="My table" charset="utf8">
        <column name="id" xsi:type="int" padding="5" unsigned="true" identity="true" nullable="false"></column>
        <column name="name" xsi:type="varchar" nullable="false" length="124"></column>
        <column name="description" xsi:type="text" nullable="true"></column>
        <column name="created_at" xsi:type="timestamp" default="CURRENT_TIMESTAMP"></column>
        <column name="updated_at" xsi:type="timestamp" default="CURRENT_TIMESTAMP" on_update="true"></column>
    </table>
</schema>

1. Manually or
2. Automatically by running below command

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

If the Vendorname_Modulename is not specified, then the default behavior is to generate a whitelist for all the modules in a system.

Check your etc folder of your module, db_schema_whitelist.json file must have generated.

Can we create db_schema_whitelist.json file for all modules?

We can create db_schema_whitelist.json file for all module using below command:

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

You can also refer to the official document for more details.

Do comment below giving your feedback.