What is bin/magento setup:upgrade ?

<code>bin/magento setup:upgrade</code> is the umbrella command — it internally runs both <code>setup:db-schema:upgrade</code> (applies every unapplied <code>Setup/Patch/Schema/*.php</code> and processes <code>db_schema.xml</code> declarative schema diffs) and then <code>setup:db-data:upgrade</code> (applies every unapplied <code>Setup/Patch/Data/*.php</code>). The two split commands exist so you can apply schema-only changes during the maintenance window and run data-only patches later out-of-band on a smaller window — useful when the data patch is expensive (millions of rows) but the schema change is trivial. 95% of the time you just run <code>setup:upgrade</code> and let Magento orchestrate both. The split-command pattern is documented in Adobe’s DevDocs but underused in practice; worth knowing about for big-table data migrations.

"Area code not set" almost always means a data patch is calling a class that tries to resolve a store context before Magento has bootstrapped a store — the patch is running in <code>adminhtml</code> area but the class wants <code>frontend</code>. Wrap the offending call in <code>$this->appState->emulateAreaCode(Area::AREA_FRONTEND, fn() => ...)</code>. "log_bin_trust_function_creators" is a MySQL replication-safety guard — Magento’s declarative schema diff creates stored functions, and binary-log-replicated DBs refuse them unless the flag is on. Fix is <code>SET GLOBAL log_bin_trust_function_creators = 1</code> as root, but the value resets on MySQL restart — bake it into <code>my.cnf</code> or your docker compose (see <code>feedback_mysql_log_bin_trust_persistent</code>) so it survives restarts.

In a local dev environment, yes — nobody is hitting your storefront, the schema change risk is zero, and you can iterate fast. In a staging environment with a small test team, yes if you have a Slack heads-up culture and accept that any QA session in flight will fatal. In production, never. Customers will hit a half-migrated schema between the moment <code>setup:upgrade</code> alters the first table and the moment it finishes the last data patch — that window is anywhere from 10 seconds (small store, no schema diff) to 20 minutes (multi-GB tables, big declarative-schema delta). Production deploys without <code>maintenance:enable</code> are how stores end up with corrupt orders, half-imported customers, and angry support tickets. Wrap every production upgrade in the maintenance window, every time.

Magento sees a patch as applied when its FQCN exists as a row in <code>patch_list</code>. To force a re-run: <code>DELETE FROM patch_list WHERE patch_name = 'Vendor\Module\Setup\Patch\Data\YourPatchName';</code> followed by <code>bin/magento setup:upgrade</code>. Magento will see the patch as unapplied and execute it again. Important: design data patches to be idempotent — use <code>INSERT … ON DUPLICATE KEY UPDATE</code> or check <code>SELECT</code>-then-<code>INSERT</code>, never plain <code>INSERT</code> — otherwise the re-run produces duplicate rows. The full rationale is in <code>feedback_data_patch_idempotency</code>. The alternative is to write a brand-new patch class with a new FQCN that performs the corrected change; less surgical but lower risk on production.

It shouldn’t — and on a properly-configured production-mode install, it doesn’t. The trick is the <code>--keep-generated</code> flag and the deploy mode. In default mode, <code>setup:upgrade</code> wipes <code>generated/code/</code> at the start so Magento can regenerate proxies on-the-fly during request handling. In production mode (<code>bin/magento deploy:mode:set production</code>), Magento refuses to regenerate at runtime — you must run <code>setup:di:compile</code> after <code>setup:upgrade</code>. If you’ve already pre-built <code>generated/code/</code> as part of an immutable deploy artifact and just want <code>setup:upgrade</code> to apply DB patches without touching the generated tree, pass <code>--keep-generated</code>. Then run di:compile only if a module’s di.xml actually changed.

Five phases. (1) Magento reads <code>app/etc/config.php</code> for the enabled-modules array and walks every enabled module’s <code>Setup/Patch/</code> directories. (2) It computes the dependency DAG from each patch’s <code>getDependencies()</code> and sorts patches topologically. (3) For each unapplied schema patch (FQCN not in <code>patch_list</code>), it runs <code>apply()</code>, then INSERTs the FQCN into <code>patch_list</code>. The same for declarative <code>db_schema.xml</code> diffs — Magento computes the diff between current DB state and the declared XML and runs the ALTER TABLEs. (4) For each unapplied data patch, same loop. (5) <code>setup_module.schema_version</code> and <code>data_version</code> for each module are updated, <code>app/etc/config.php</code> is rewritten with the current enabled-modules list (in case <code>module:enable</code>/<code>module:disable</code> changed it), and the config cache is invalidated so the next request re-reads the new module list and applied patches. In default mode there’s a sixth phase: wipe and regenerate <code>generated/code/</code>. Production mode skips that phase — you run di:compile separately.