![Platform Update Migration Checklist: 8 Tests [2026]](/images/blog/platform-update-migration-checklist-8-tests-2026.jpg)
Every major platform update looks safe in the changelog until you push it to production and discover your application won't start. The cost of downtime during a failed migration is high—lost revenue, frustrated users, emergency rollbacks at 2 AM. I've seen teams skip pre-migration testing because "it's just a minor version bump" only to spend the next twelve hours debugging breaking changes in a live environment.
The eight tests below catch the breaking changes that matter. Run them in your staging environment before the update touches production, and you'll know exactly what will break and how to fix it.
1. Dependency compatibility scan
Start by checking whether your application dependencies are compatible with the new platform version. Language runtime updates often break older libraries, and package managers don't always flag the conflict until install time.
For a PHP update, run Composer's platform check:
composer check-platform-reqs
For Node.js, audit your package.json engines field against the new runtime and run:
npm ls
Look for peer dependency warnings and deprecated packages. Python projects should verify requirements.txt against the new interpreter with a clean virtual environment.
The goal is a list of incompatible packages before you commit to the update. Fix or replace them now, not during a production rollback.
2. Database schema and query compatibility
Database engine updates change query behavior, deprecate syntax, and tighten type enforcement. A query that worked under MariaDB 10.5 might fail under 10.11 because of stricter GROUP BY rules or removed storage engine support.
Export your schema and run it through the new database version in staging:
mysqldump -u root -p --no-data yourdb > schema.sql
mysql -u root -p --force < schema.sql 2> errors.log
Review errors.log for deprecated syntax. Then run your application's automated test suite against the new database and watch for query failures. Pay special attention to:
- Default collation changes
- Reserved keywords that are now restricted
- Removed or renamed system variables
- Altered
DATETIMEorTIMESTAMPbehavior
If you rely on stored procedures or triggers, test those separately. They're often the first things to break.
3. Environment variable and configuration drift
Platform updates sometimes introduce new required configuration keys or change the format of existing ones. Your application might start with missing variables or silently fall back to incorrect defaults.
Diff your current environment file against the new platform's expected format. For containerized applications, compare the old and new base images:
docker run --rm old-image:tag env | sort > old-env.txt
docker run --rm new-image:tag env | sort > new-env.txt
diff old-env.txt new-env.txt
For server environments, check whether the new platform reads configuration from different paths. Apache 2.4 to 2.5 migrations, for example, might move module configs or change the directory structure under /etc.
Document every new or changed variable and decide whether your application needs them set explicitly.
4. SSL/TLS and cryptographic library changes
OpenSSL updates and TLS policy changes can break connections to external APIs, SMTP relays, and payment gateways without throwing obvious errors. A tightened cipher suite or disabled protocol version means your application can't complete the handshake.
Test outbound HTTPS connections from your staging environment after the platform update:
curl -v https://api.example.com
openssl s_client -connect smtp.example.com:587 -starttls smtp
Watch for handshake failures or cipher mismatches. If your application makes payment API calls, test those endpoints specifically. Older payment gateways sometimes require TLS 1.0 or 1.1, which modern platforms disable by default.
Verify your own SSL certificates still load correctly and that automatic renewal hooks (Let's Encrypt, Certbot) still work.
5. File permission and ownership changes
Some platform updates change the default user, group, or umask for web server processes. Files that were writable under the old configuration might become read-only, breaking uploads, caches, and log writes.
After applying the update in staging, test every directory your application writes to:
sudo -u www-data touch /var/www/html/uploads/test.txt
sudo -u www-data touch /var/www/html/cache/test.tmp
If those commands fail, check the directory owner and permissions:
ls -ld /var/www/html/uploads
PHP-FPM pool user changes and containerized application UID shifts are common culprits. Fix ownership before the update goes live:
chown -R www-data:www-data /var/www/html/uploads
6. Third-party integration and webhook endpoints
Webhook receivers and API integrations fail silently when the platform update changes request headers, TLS requirements, or IP addresses. Your payment gateway might stop notifying you of successful transactions, or your monitoring service might lose contact.
Fire test webhooks at your staging environment from every external service you integrate with. Check your application logs for incoming requests and verify the payloads parse correctly. If the platform update changes your server's outbound IP (common in managed hosting migrations), update firewall rules and IP allowlists at your third-party providers.
For services that validate webhook signatures, confirm your signing secrets still match.
7. Scheduled task and cron job execution
Cron behavior and available system utilities change between platform versions. A scheduled backup script that worked under one version of tar might fail under another, or the new platform might use a different cron daemon with stricter syntax rules.
Migrate your crontab to staging and manually trigger each job:
crontab -l > crontab.backup
crontab -e # paste into staging
Then force-run each scheduled command:
/usr/bin/php /var/www/html/artisan schedule:run
Check that paths, interpreters, and environment variables are still correct. Modern systemd-based platforms sometimes replace cron with systemd timers, which require different syntax.
8. Rollback plan validation
The final test is proving you can roll back cleanly if the migration fails in production. A rollback plan you haven't tested is just a wishlist.
Document the exact steps to revert to the previous platform version, then execute those steps in staging:
- Restore the old database snapshot
- Redeploy the previous application version
- Revert configuration files and environment variables
- Switch DNS or load balancer targets back if needed
Time how long the rollback takes. If it's more than a few minutes, identify the bottleneck and optimize it. In production, you'll be executing this rollback under pressure with users waiting.
Keep a copy of the old platform's package list or container image tag so you can rebuild it exactly.
Run the checklist twice
The first time you run through these eight tests, you'll find issues. That's expected. Fix them, then run the checklist again from the top to confirm your fixes didn't introduce new problems. A clean second pass means your migration is ready.
Schedule the production update during low-traffic hours, keep your rollback commands ready, and monitor logs closely for the first few hours after the switch. If you tested thoroughly, the update will be boring—which is exactly what you want.