Question
Contao 5 Zero-Downtime Migration: Official Upgrade Bundle vs Custom Scripts
Lax Moss
0 reputation · 06 Apr 2020, 06:13 UTC
95.6K views1
Loading…
0 reputation · 06 Apr 2020, 06:13 UTC
Migrate a small Contao 5 application to a newer minor release without user-facing downtime.
Contao 5 offers maintenance mode through the install tool, but enabling it locks the site and can be perceived as downtime. Blue-green requires two identical environments; rolling update keeps old and new code together and risks schema or cache mismatches during transition.
The official Contao upgrade bundle handles schema changes automatically, but it may tie the app to a specific core version and reduce flexibility for a small app. Custom scripts preserve control yet require manual schema updates and cache clearing.
This behavior needs confirmation against current Contao documentation before production planning.
Can the official Contao upgrade bundle apply schema changes on Contao 5 without activating maintenance mode?
For a single-server deployment, is a custom migration script preferable to maintaining a parallel blue-green environment?
What cache-clearing behavior is expected when old and new Contao versions share the same database during transition?
Can the official upgrade bundle apply schema changes without maintenance mode? No. The contao/upgrade-bundle automates Doctrine migrations but internally enables maintenance mode via contao:maintenance:lock (Contao 5.3+) or the install tool's web UI. Schema changes are not backward-compatible; running old code against a migrated schema breaks immediately.
Is a custom migration script preferable to blue-green on a single server? Yes, for most small apps. A scripted sequence — deploy new code to a parallel directory, run migrations in maintenance mode, atomic symlink swap, clear cache — avoids doubling infrastructure. Blue-green only pays off if rollback must be instantaneous without CLI access.
What cache-clearing behavior occurs when versions share a database? The var/cache directory is version-isolated by deployment path, but shared database caches (Redis/Memcached) collide unless cache.prefix_seed in config/packages/contao.yaml includes a version identifier. Run contao:cache:clear (or cache:pool:clear) after migration and before traffic switch.
| Aspect | Confirmed (docs/CLI) | Likely / Version-Dependent |
|---|---|---|
| Upgrade bundle maintenance mode | Uses contao:maintenance:lock (5.3+) | No "no-downtime" flag exists in any 5.x release |
| Schema backward compatibility | Column renames/type changes break old code | Exact migration list varies by minor version |
| Cache key collision | Shared Redis/Memcached keys collide without prefix | Default prefix behavior may differ in 5.1 vs 5.3 |
| Custom script safety | Atomic symlink swap works on Linux/Unix | Windows symlink permissions may require admin |
contaocomposer require contao/upgrade-bundle --no-update (if not present), then composer update contao/upgrade-bundle in a staging clone.php vendor/bin/contao-console contao:migrate --dry-run on a database copy. Note migration count and estimated time./var/www/project_new, run composer install --no-dev.php vendor/bin/contao-console contao:maintenance:lock (5.3+) or enable via install tool.php vendor/bin/contao-console contao:migrate (or doctrine:migrations:migrate).php vendor/bin/contao-console contao:cache:clear --no-warmup then contao:cache:warmup.ln -sfn /var/www/project_new /var/www/project_live (update web-root symlink).php vendor/bin/contao-console contao:maintenance:unlock.tl_version matches new release.What is your exact Contao version (composer show contao/core-bundle | grep versions)? Contao 5.1, 5.2, and 5.3 differ in migration tooling and maintenance-mode commands; the sequence above assumes 5.3+. If you are on 5.1/5.2, the contao:maintenance:lock command may not exist and you must use the install tool's web UI or direct database flag update.
# Confirm upgrade bundle version
composer show contao/upgrade-bundle
# List pending migrations without executing
php vendor/bin/contao-console contao:migrate --dry-run
# Inspect cache prefix configuration
grep -A5 'cache:' config/packages/contao.yaml
# Test full sequence on DB copy
php vendor/bin/contao-console contao:maintenance:lock
php vendor/bin/contao-console contao:migrate
php vendor/bin/contao-console contao:cache:clear
php vendor/bin/contao-console contao:cache:warmup
php vendor/bin/contao-console contao:maintenance:unlock
Use comments to ask for clarification. Post a solution as an answer.
35,775 reputation · 06 Apr 2020, 08:29 UTC
When executing a custom migration script, the var/cache directory must be cleared after the schema migration but before the traffic switch. Contao 5's cache:warmup command rebuilds the container and routes based on the new codebase, but if the old cached container is still present, Symfony may attempt to use stale service definitions that reference removed or changed classes.
Practical sequence for single-server deployment:
/var/www/app_newcontao:maintenance:lock)rm -rf /var/www/app_new/var/cache/*cache:warmup with APP_ENV=prodln -sT /var/www/app_new /var/www/app_currentThis keeps downtime to the maintenance mode window only, typically 10–30 seconds for small schemas.