Upgrading 1.5.7c Database to a Fresh Install of 2.2.2

Hi Zen team, Thank you for always upgrading/maintaining Zen Cart, your time & effort is much appreciated :)

I just did a fresh install of 2.2.2 as upgrading from 1.5.7c is not an option for me right now.
I copied over the 1.5.7c Database and updated it using the zc_install.
I also copied the images to the new site images folder.

Is there anything else I need to do before I start installing plugins etc.?

G'Day

Yes, a few things, and one of them changes the order in which you do everything.

1. That database copy will go stale. If the 1.5.7c store is still taking orders while you build the 2.2.2 site, everything you do to the new database now (plugin installs, settings, layout) gets thrown away when you copy the live database again at go-live. So either put the old store in maintenance mode and build quickly, or treat this round as a rehearsal: write down every step, then at cutover re-copy the database, re-run the zc_install upgrade, and replay the list. Don't try to merge orders between two databases by hand.

2. Check that the upgrade actually finished. Admin > Tools > Server/Version Info should show a database patch level of 2.2.2, and there should be nothing in logs/ from the install. zc_install upgrades 1.5.7c to 2.2.2 in one pass, so if it says 2.2.2 you're good. Then delete the zc_install folder and set both configure.php files read-only.

3. Character set. The upgrade does NOT convert your tables to utf8mb4. Your copied tables are still utf8 (utf8mb3), while a fresh 2.2.2 configure.php says DB_CHARSET = 'utf8mb4'. That mostly works, but anything with emoji or unusual characters in product text or customer names will break. Either convert the tables to utf8mb4 (phpMyAdmin or a one-off SQL run, on a backup first) or set DB_CHARSET to utf8 in both configure.php files until you do.

4. The old plugins came along in the database, without their files. Every plugin you had on 1.5.7c left configuration keys, admin menu entries, possibly its own tables, and rows in plugin_control. Their files aren't on the new site. Go to Admin > Tools > System Inspection and read the whole page: it lists the admin pages registered to files that don't exist, config groups with no page, and the modules whose files are missing. That's your cleanup list. For each one, run the old plugin's uninstall SQL against the new database, or check whether the 2.x version's installer says it handles a legacy install (lat9's plugins mostly do). Installing on top of stale rows is how you get "duplicate entry" errors and half-installed plugins. Then go to Admin > Modules, remove any payment, shipping, or order total modules that System Inspection flagged, and install the 2.x replacements. Re-run System Inspection until it comes up clean.

5. Template. The database still points at your old template, which probably isn't on the new site, and it wouldn't run on 2.2.2 anyway (2.x changed the language file format and added notifiers a 1.5.7 template doesn't call). Go to Admin > Tools > Template Selection, set responsive_classic or the Bootstrap template, then visit Layout Boxes Controller once so it creates the box rows for that template. Rebuild your look as a thin clone of one of those; don't copy the old template folder over.

6. Things that live in files, not the database. These didn't come across with the database and need copying or redoing:

- Define pages (includes/languages/english/html_includes/<template>/define_*.php): shipping, privacy, conditions, about us, main page text. Copy and re-check them. On PHP 8, unquoted constants in an old define_main_page.php are fatal, not a warning.

- Custom language overrides from includes/languages/english/<template>/: these are the old define() format and must be converted to 2.x lang.*.php arrays, not copied.

- Customized email templates in email/: re-apply your changes to the 2.2.2 versions.

- The download/ folder if you sell downloadable products, media/ if you have music products, plus your .htaccess and robots.txt customizations.

- Time zone: 2.x sets it in includes/extra_configures/set_time_zone.php ($TZ); set it to your Australian time zone.

7. Then look before you install anything. Log in to the admin, click through every menu, and open the storefront with logs/ empty. Fix whatever's broken in core first. Only then start plugins, one at a time, checking logs/ after each.

Once the new site is right, the go-live is just step 1 again: freeze the old store, copy the database, upgrade, replay your list, switch DNS.

G'day John, hope all is well, it's been a while.

Thank you very much for that great and detailed response, I knew there had to be more steps :)

I will start working on your recommendations.

Ok, going through the log files since the database upgrade. Nothing much in there, not sure if I need to do anything for them.

Zen Cart 2.2.2

Database Patch Level: 2.2.0 (Should this part be 2.2.2 instead of the 2.2.0??)

v2.2.2 [2026-09-22 20:13:19] (Version Update to 2.2.2)

v2.1.0 [2026-09-22 20:13:19] (Version Update 2.0.0->2.1.0)

v2.0.0 [2026-09-22 20:13:19] (Version Update 1.5.8->2.0.0)

v1.5.8 [2026-09-22 20:13:18] (Version Update 1.5.7->1.5.8a)

Here are some things from log files in (zcInstallDEBUG):

[22-Sep-2026 20:13:18 America/Chicago] MySQL error 1091 encountered during zc_install:

Can't DROP 'final_price'; check that column/key exists

ALTER TABLE zen_customers_basket DROP final_price;

---------------

[22-Sep-2026 20:13:18 America/Chicago] MySQL error 1091 encountered during zc_install:

Can't DROP 'languages_id'; check that column/key exists

ALTER TABLE zen_ezpages DROP languages_id;

---------------

[22-Sep-2026 20:13:18 America/Chicago] MySQL error 1091 encountered during zc_install:

Can't DROP 'pages_title'; check that column/key exists

ALTER TABLE zen_ezpages DROP pages_title;

---------------

[22-Sep-2026 20:13:18 America/Chicago] MySQL error 1091 encountered during zc_install:

Can't DROP 'pages_html_text'; check that column/key exists

ALTER TABLE zen_ezpages DROP pages_html_text;

---------------

Here are some things from log files in (zcInstallLog):

Sep 22 2026 20:13 -- upgradeException

ALTER TABLE zen_customers_basket DROP final_price; 1091: Can't DROP 'final_price'; check that column/key exists

---------------

Sep 22 2026 20:13 -- upgradeException

ALTER TABLE zen_ezpages DROP languages_id; 1091: Can't DROP 'languages_id'; check that column/key exists

---------------

Sep 22 2026 20:13 -- upgradeException

ALTER TABLE zen_ezpages DROP pages_title; 1091: Can't DROP 'pages_title'; check that column/key exists

---------------

Sep 22 2026 20:13 -- upgradeException

ALTER TABLE zen_ezpages DROP pages_html_text; 1091: Can't DROP 'pages_html_text'; check that column/key exists

Here are some things from log files in (zcInstallLog 2):

Sep 22 2026 20:13 -- Running upgrade SQL

/home2/zc_install/sql/updates/mysql_upgrade_zencart_200.sql

---------------

Sep 22 2026 20:13 -- upgradeException

ALTER TABLE zen_products MODIFY products_length DECIMAL(8,4) DEFAULT NULL; Cannot CHANGE column products_length because it does not exist. /home2/zc_install/sql/updates/mysql_upgrade_zencart_200.sql

---------------

Sep 22 2026 20:13 -- upgradeException

ALTER TABLE zen_products MODIFY products_width DECIMAL(8,4) DEFAULT NULL; Cannot CHANGE column products_width because it does not exist. /home2/zc_install/sql/updates/mysql_upgrade_zencart_200.sql

---------------

Sep 22 2026 20:13 -- upgradeException

ALTER TABLE zen_products MODIFY products_height DECIMAL(8,4) DEFAULT NULL; Cannot CHANGE column products_height because it does not exist. /home2/zc_install/sql/updates/mysql_upgrade_zencart_200.sql

---------------

Sep 22 2026 20:13 -- upgradeException

ALTER TABLE zen_products CHANGE products_ready_to_ship product_ships_in_own_box TINYINT DEFAULT NULL; Cannot CHANGE column products_ready_to_ship because it does not exist. /home2/zc_install/sql/updates/mysql_upgrade_zencart_200.sql

---------------

Sep 22 2026 20:13 -- upgradeException

ALTER TABLE zen_products MODIFY product_ships_in_own_box TINYINT DEFAULT NULL; Cannot CHANGE column product_ships_in_own_box because it does not exist. /home2/zc_install/sql/updates/mysql_upgrade_zencart_200.sql

System Inspection Log:

New Admin Pages

(BOX_REPORTS_SEARCH_LOG) reports Y [Unable to create a Link to this]

(BOX_TOOLS_IMAGE_HANDLER) tools Y [Unable to create a Link to this]

(BOX_TOOLS_IMAGE_HANDLER_UNINSTALL) tools N [Unable to create a Link to this]

(BOX_TOOLS_IMAGE_HANDLER_VIEW_CONFIG) tools N [Unable to create a Link to this]

Not sure what I need to do to remove the above, I've ran sql to remove the other plugins (Colorbox, One Page Checkout, SitemapXML and EditOrders).

Next, I went to Operations in PHPMyAdmin, Collation, ticked both boxes and converted my database to utf8mb4_unicode_ci.

G'Day

You're close. Most of what's in those logs is harmless, but one part needs fixing before you go any further.

1. Patch level 2.2.0. My mistake in the earlier post. The database version only changes when the database schema changes, and I believe the 2.2.x point releases after 2.2.0 didn't change it. Open includes/version.php in your 2.2.2 files and look at PROJECT_DB_VERSION_MAJOR / MINOR. If they say 2 and 2.0, then 2.2.0 is correct, and your history showing "Version Update to 2.2.2" means the upgrade ran to the end.

2. The four "Can't DROP" errors (customers_basket.final_price, ezpages.languages_id / pages_title / pages_html_text). These are harmless. The 1.5.8 step tries to drop columns that were already gone. The end result it wants, those columns not being there, is what you have. To be sure, open a couple of EZ-Pages in the admin and check that the titles and content are still there.

3. The zen_products errors. These need fixing. The 2.0.0 step tried to modify products_length, products_width, products_height and rename products_ready_to_ship to product_ships_in_own_box. All four failed because the columns didn't exist. 2.x expects those columns, so you'll probably get SQL errors when you save a product. Check first:

sql
SHOW COLUMNS FROM zen_products;

If any of products_length, products_width, products_height or product_ships_in_own_box is missing, back up and add the missing ones:

sql
ALTER TABLE zen_products
ADD products_length DECIMAL(8,4) DEFAULT NULL,
ADD products_width DECIMAL(8,4) DEFAULT NULL,
ADD products_height DECIMAL(8,4) DEFAULT NULL,
ADD product_ships_in_own_box TINYINT DEFAULT NULL;

(Leave out any that already exist.) Then edit a product, save it, and check logs/. If you still have the database from your fresh 2.2.2 install, compare its zen_products structure with this one. That's the best reference you have.

4. System Inspection leftovers. Those are Search Log and the old Image Handler, both still registered in the admin menu without their files. If you're not putting them back:

sql
DELETE FROM zen_admin_pages WHERE language_key IN
('BOX_REPORTS_SEARCH_LOG','BOX_TOOLS_IMAGE_HANDLER',
'BOX_TOOLS_IMAGE_HANDLER_UNINSTALL','BOX_TOOLS_IMAGE_HANDLER_VIEW_CONFIG');

Image Handler also left configuration settings and a configuration group behind. Run a SELECT on configuration WHERE configuration_key LIKE 'IH%' to see them before you delete anything. For Search Log, check SHOW TABLES LIKE '%search%' for its table. If you plan to use Image Handler 5 on 2.2.2, read its install notes first, since it may deal with an old install for you. Re-run System Inspection until it comes up clean.

5. utf8mb4. Doing it through Operations > Collation with both boxes ticked is fine. Make sure DB_CHARSET is 'utf8mb4' in both configure.php files. Then look at a few products and customer names with accented letters or curly quotes. If they show garbled characters like é now, the old data was double-encoded, and the conversion alone won't fix that. Let us know if you see it.

After that, do the admin click-through and check the storefront with logs/ empty, and then start on plugins.

Thanks once again.

Here is what it says in includes/version.php file.

define('PROJECT_VERSION_MAJOR', '2');

define('PROJECT_VERSION_MINOR', '2.2');

define('EXPECTED_DATABASE_VERSION_MAJOR', '2');

define('EXPECTED_DATABASE_VERSION_MINOR', '2.0');

I've checked my ezpages, and the title is still the same, didn't have any content/description as they were just links to another stock page.

As for the zen_product_errors, I checked the Database and the (products_length, products_width, products_height or product_ships_in_own_box) are there, I can see them in the admin when I edit a product, no error logs when updating a product.

I also deleted the Image Handler and Box Report Search Log entries from the Database. (NO error in log files after doing so :) I will install IH5 but at least there's nothing from IH4 in the database.

Finally, I checked BOTH config.php files and they are set to DB_CHARSET is 'utf8mb4'.
This is what it shows from version in admin under database configuration variables:

character_set_client utf8mb4
character_set_connection utf8mb4
character_set_database utf8mb4
character_set_filesystem binary
character_set_results utf8mb4
character_set_server utf8
character_set_system utf8
character_sets_dir /usr/share/percona-server/charsets/
check_proxy_users OFF
collation_connection utf8mb4_general_ci
collation_database utf8mb4_unicode_ci
collation_server utf8_unicode_ci

Well thank you again, after your detailed guidance, I think I might be good to start installing some plugins 🙂