Upgrade Preparation
Sugerir una ediciónPrepare and verify a platform upgrade without re-running fresh installation or risking store data.
On this pageJump to a section
Separate a fresh install from an additive upgrade, rehearse on staging, and keep a tested rollback path.
Understand the upgrade boundary
A fresh installation loads the install schema into an empty database. An existing store must use the upgrade mechanism for the release, which applies additive patches rather than reimporting the full schema. Do not run a fresh-install SQL dump, migrate:fresh, database reset, or installer over live orders.
Confirm the currently installed version, target release, supported PHP/build tools, theme changes, and extension compatibility. A higher package version is not proof that all third-party integrations are compatible.
Back up before changing anything
- Export the database and verify that the export can be read and restored.
- Preserve .env and APP_KEY securely; they are not disposable setup files.
- Copy uploads/storage, installed extensions, child themes, and custom configuration such as the admin-path file.
- Record current versions and keep the previous release package. Store recovery material outside the public web root.
For busy stores, choose a maintenance window and a strategy for orders arriving during the upgrade. A rollback to an older database can discard orders placed after the backup.
Rehearse on a staging copy
- Restore a backup to a separate database and non-public/staging environment.
- Disable real payment capture and outgoing customer messages on that copy.
- Place the intended release files according to the release’s deployment instructions, preserving configuration and user data.
- Inspect the dry-run output, then apply the upgrade only to the staging copy.
- Test storefront, admin, account, checkout, images, mail configuration, and enabled extensions.
php artisan wento:upgrade --dry-runA dry run helps identify pending upgrade work but does not replace a backup or integration tests. Keep any release-specific instructions with your deployment record.
Apply the approved upgrade
After staging is accepted and the production backup is verified, use the release’s supported CLI flow during the agreed maintenance window:
php artisan wento:upgrade --backup --forceRun it only on the intended environment after reviewing the dry run and backing up. The –force flag is not a substitute for preparation. Do not copy this into a fresh-install walkthrough.
The source documents backups under storage/app/upgrades/backups/{id}/, including database, core files, a manifest, and recovery credentials. Treat recovery credentials as secrets. Rebuild/publish assets only as required by the release and restart relevant long-running processes.
Validate or roll back
Check the upgraded version, application logs, key admin operations, an end-to-end test order, payment handling, and customer access before ending maintenance. Check extension health and any staged extension upgrades separately.
The release provides wento:upgrade-restore and an emergency wento-recovery.php path for supported backup recovery. Review the checkout’s docs/UPGRADE.md and record the exact backup id before using restore. Restoring affects files/data; assess new orders first and use a maintenance window.
Protect future upgrades
Put customizations into supported extensions and child themes instead of changing core files. Keep a short deployment log: version, backup, patches, tests, operator, and any follow-up. If the shop is already failing, diagnose the error before repeatedly running upgrade or installer commands.
Continue learning
Backups & Maintenance · Build an Extension · Installation Errors