Magento setup:upgrade: What It Does and When to Run It

bin/magento setup:upgrade applies database schema and setup-data changes required by the Magento code being deployed. It can change stored data and table structure. It does not download an upgrade, solve Composer conflicts or prove that checkout still works.

A useful question before running it is: what changed in this release that needs the database to change? Installing or updating an extension may introduce a table, an attribute or a data patch. A template edit usually has a different deployment requirement. Treat the command as a database-changing deployment step, rather than a general repair for a slow or broken page.

What setup:upgrade processes

The exact work depends on the installed release and modules. In modern Magento, modules can declare their intended table structure in db_schema.xml. Declarative setup compares that structure with the existing database and determines the required operations. A declaration can remove something as well as add it, so a successful syntax check is not enough to approve the change. Adobe describes this model in its declarative schema reference.

Modules can also provide schema patches and data patches. A schema patch handles a schema change that needs procedural code; a data patch can create or update application data. Declarative schema runs before these patches, and declared patch dependencies determine required ordering. Legacy setup scripts may also matter in older or mixed modules. Review the actual extension source instead of assuming every module uses one mechanism.

For example, an extension might declare a new table and supply a data patch that creates an attribute used by that table's feature. The database step needs both parts to agree with the deployed code. It does not establish that the resulting Admin form or storefront behavior is correct.

Why patch history is not a reset button

Magento records applied patches in patch_list. An already applied patch is normally skipped on a later run. Editing an old patch file therefore does not mean that existing installations will receive its new behavior. Adobe's patch documentation explains patch history, dependencies and aliases.

Keep that history intact. If a module needs another data change, the normal development approach is a new, reviewed patch with the right prerequisites and checks for existing state. Forcing an old patch to run again can repeat inserts, overwrite newer values or revisit a destructive operation. A revert method is not a general undo button for an individual deployed patch.

If an upgrade fails, do not assume that nothing changed. Capture the first relevant error privately and determine which operations completed before choosing a retry or recovery path. That decision belongs to the specific release and affected data, not to a generic reset recipe.

Before the database step

1. Fix the deployment inputs. Confirm the intended release, extension versions and reviewed dependency lockfile. Resolve package problems before applying the release's database changes.
2. Rehearse with representative data. Test the same code against an appropriate protected copy. Check the planned schema and data changes and verify that recovery is usable; the existence of a backup file is not a restoration test.
3. Control concurrent work. Follow the deployment platform's maintenance and background-work procedure. Maintenance mode alone is not evidence that cron jobs, consumers or integrations have stopped writing. Adobe's upgrade procedure calls out asynchronous work.
4. Use the correct project and account. Run approved deployment steps as the application's file-system owner with the intended PHP runtime. Investigate a specific permission or database error instead of applying broad ownership changes or changing shared database settings.

The command itself is bin/magento setup:upgrade. This is a write operation, not a diagnostic probe. Run it only as the prepared deployment step for the intended environment. Adobe's database-upgrade instructions document its purpose and options.

Generated code, assets and cache are separate concerns

There is no safe command bundle for every deployment. Single-machine releases and pipelines can prepare artifacts at different stages. Cloud projects have their own supported workflow. Match the procedure to the installation method and release; Adobe's deployment overview explains that separation.

• DI compilation prepares dependency-injection artifacts. It does not apply database patches.
• Static content deployment prepares theme and locale assets. It does not prove that a database change is complete.
• --keep-generated is a limited preservation option, not an instruction to reuse arbitrary artifacts. Adobe restricts its documented use to experienced integrators in production mode. Use it only when the deployment design establishes that the prepared artifacts match the code.
• Clean the relevant Magento cache as the release procedure requires. Adobe distinguishes cleaning application cache from purging storage that other applications may share in its cache guide. A broad storage purge is not a default upgrade step.

What to check after success or failure

After a successful database step, check the deployment status and the feature that required the change. For an attribute patch, verify the intended attribute and its behavior. For a schema change, check that the updated module can use it. Then test the store's relevant browsing, account, cart, checkout, order and background-work flows before reopening it.

bin/magento setup:db:status is the documented database-status check. It requires a correctly configured application and database access. A normal status is useful setup evidence, not a functional test or proof that custom data has the intended values.

On failure, keep the deployment controlled while you identify the failing component and actual database state. Preserve useful errors without sharing secrets or customer data. Repeating the command, changing history or rolling back only the code can leave the underlying mismatch unresolved. Use the tested recovery plan when forward repair is not appropriate.