Updating to a new version
Replace the files, run one command, and know which three things must survive.
The three things that must survive
Everything else in the package can be overwritten. These cannot:
| Path | Holds | If you lose it |
|---|---|---|
config/config.php | Your database credentials and keys. | The site cannot connect to its own database. |
assets/uploads | Every image anybody has ever uploaded. | Every dish photograph, logo and cover, gone. |
| Your database | Everything else. | Everything. |
The procedure
- Back up the database and
assets/uploads. Not optional, and not worth skipping on the grounds that it is a small update. - Turn maintenance mode on, so nobody orders halfway through — see Maintenance mode & backups.
- Replace the application files with the new release, keeping the two paths above.
- Run the database upgrade:
php database/migrate.php- Turn maintenance mode off and check the storefront, a dashboard, and one order.
What the upgrade runner does
It brings an older database up to the new release's schema. Four properties are worth knowing, because they decide how safe a bad moment is:
| Property | Meaning |
|---|---|
| It only ever adds | Nothing is dropped and no row is deleted. An upgrade cannot lose your data. |
| It is idempotent | Every step checks the database before changing it. Running it twice changes nothing. |
| It records what it applied | A step cannot double-apply. |
| A failed run is re-runnable | Fix the cause and run it again. It picks up where it stopped. |
On a fresh install it reports there is nothing to do — the installer creates the database at the current schema, so every step is already applied.
What survives and what does not
| Survives | Does not |
|---|---|
| Everything set in the dashboard — settings, branding, page wording, menus, plans. | Edits you made to PHP, CSS or JavaScript files. |
| All your data. | Changes to the shipped language files. |
| Uploaded images, if you preserved the folder. | Anything you added inside a folder the release replaces. |
If you have customised code, keep a record of what and where. A diff against the previous release is the reliable way to reapply it.
Afterwards
- Check the scheduled tasks screen. A new release may add a job, and new jobs follow their own default rather than inheriting a decision you never made.
- Look at Settings → Payment and confirm webhooks are still arriving.
- Place one test order end to end. It exercises more of the product than any amount of reading does.
When it doesn't work
A blank page or a database error straight after updating
The migration has not been run. That is the first thing to try.
"config/config.php not found"
Your configuration file was overwritten or removed. Restore it from your backup — this is why step one exists.
Every image is missing
assets/uploads was replaced. Restore it from the backup.
A customisation disappeared
It was in a file the release replaced. Reapply it from your record.
The migration reports nothing to do
The database is already current. That is a pass, not a failure.