Appearance
Source:
docs/research/migrations-on-deploy.md. Edit it there; this page is generated at build time.
Migrations on deploy, and what rollback can honestly mean
Research for issue 17, under the release map in issue 13. Everything below is checked against primary sources — vendor documentation and framework source — and where a source is silent or thin, this says so rather than filling the gap with reasoning.
The recommendation
Keep automatic migrate --force on every deploy. Move it to run before the symlink flip, not after. Keep the pre-migration dump, but move it out of the release directory. And add the one rule that makes the whole arrangement honest: every migration in a tagged release must be safe against the code of the release before it.
That last clause is the actual finding. The charting-time assumption — auto migrate --force, preceded by a dump kept beside the release — is defensible, but it is defensible for a reason it did not state. A dump is a last-resort artefact that, on the evidence below, no first-party Laravel deploy tool takes and almost nobody ever restores. What actually makes "rollback is a symlink flip" a true sentence rather than a hopeful one is that the old code can still run against the new schema. Additive-only migrations buy that; a dump does not.
The step order the runner should execute, in full:
- Build the release beside the live one. Check the tag out into
releases/<tag>, link the shared paths (.env,storage/),composer install --no-dev --optimize-autoloader,npm ci,npm run build,php artisan optimize. Nothing here touches the database or the live site. A failure here costs a directory. - Record what is about to change.
php artisan migrate --pretend, from the new release directory, with the output captured into the Actions log. Laravel documents this as showing "the SQL statements that will be executed by the migrations without actually running them". It costs nothing and it is the only artefact that will tell you, six months later, what a release did to the schema. - Dump, if and only if something is pending.
mysqldumpto/var/backups/reviewly/pre-deploy-<tag>-<utc-timestamp>.sql.gz, with its own retention — not intoreleases/<tag>/. A dump kept inside the release is deleted by the same purge that trims old releases, which gives the safety net exactly the lifetime of the thing it is meant to outlive. - Migrate, with
currentstill pointing at the old release.php artisan migrate --force --no-interaction, run fromreleases/<tag>. This is the ordering decision the ticket asks about, and §2 below is the evidence for it. - Stop here on failure. Do not flip. The site is still serving the previous release, which is the best available outcome — but the database may be partially changed, and §5 explains why that is not a hypothetical on MySQL.
- Flip
current.ln -sfninto a temp name thenmv -Tf, so the swap is a single rename. - After the flip:
php artisan reload(Laravel 13's one command for terminating queue workers and other long-running processes), restart thequeue:workunit, and whatever PHP-FPM / opcache handling issue 18 settles. - Smoke-test.
curl -fsS https://filament.stackbridge.com.au/up— Laravel's built-in health route "will return a 200 HTTP response if the application has booted without exceptions."
And two things the workflow should not do, both argued below: do not use migrate --isolated (§6), and do not wire migrate:rollback into anything (§4).
1. What Laravel's own ecosystem actually does
The short version: the two products that say anything explicit both run migrations before the new version takes traffic, and both treat a failing migration as a reason not to activate. The two that run on your own server say nothing at all and leave the placement to you. That asymmetry is worth knowing, because it means "Laravel's ecosystem does X" is only half true, and the half that is true comes from the managed platforms.
Laravel Vapor is the most explicit source in the whole ecosystem. docs.vapor.build/projects/deployments distinguishes build hooks, which run on the machine doing the deploying, from deploy hooks:
You may define deployment hooks for an environment using the
deploykey within yourvapor.ymlfile. These commands are executed against the deployed environment before it is activated for general availability. If any of these commands fail, the deployment will not be activated.
And its own example puts exactly one thing in that key:
yaml
build:
- 'composer install --no-dev'
- 'php artisan event:cache'
deploy:
- 'php artisan migrate --force'Laravel Cloud says the same thing about timing. laravel.com/cloud/docs/environments:
Your environment's "Deploy Commands" are run on your Laravel Cloud infrastructure just before a new deployment goes "live". Typically, these commands will be used to migrate your environment's database.
Typically, your deploy commands should only include database migrations and other essential post-deployment tasks.
Cloud also draws the build/deploy line the same way Vapor does — "Running php artisan optimize or php artisan config:cache should be done during the build process, not during the deploy process" — which maps onto step 1 above. What Cloud does not document is the failure semantics: nowhere on the deployments or environments pages does it say that a failing deploy command aborts activation the way Vapor's docs do. Assume it behaves like Vapor at your own risk; this is an unverified point, not a confirmed one.
Envoyer, the first-party tool closest to what we are building, prescribes nothing. docs.envoyer.io/projects/deployment-hooks lists four fixed stages —
Envoyer creates several first-party deployment hooks that cannot be modified or re-ordered:
- Clone New Release
- Install Composer Dependencies (if you have configured your project to do so)
- Activate New Release
- Purge Old Releases
Your custom hooks can be re-ordered before / after each of these fixed actions.
— and then says nothing whatsoever about where a migration hook belongs relative to "Activate New Release". It does give the property that makes either placement survivable:
Like any other step during your deployment, if a deployment hook exits with a non-zero status code, the entire deployment will be cancelled. This prevents your application from experiencing downtime due to a broken deployment.
Laravel Forge is the same story, and the premise in the ticket needs one correction: Forge's default for new sites is no longer an in-place git pull. laravel.com/forge/docs/sites/deployments:
Laravel Forge automatically enables zero-downtime deployments for all new sites by default.
Its zero-downtime script is built from three macros — $CREATE_RELEASE(), $ACTIVATE_RELEASE() and $RESTART_QUEUES() — and the guidance is positional rather than prescriptive:
Forge adds the
cd $FORGE_RELEASE_DIRECTORYcommand after the$CREATE_RELEASE()macro in the deployment script to make sure all commands located after this code block will be executed in the context of the new release directory. [...] If you need to run any tasks after a new release has been activated, you should place those commands after the$ACTIVATE_RELEASE()macro.
Migrations are named only in the generic sentence about what a deploy script contains — "perform any other tasks needed to get your application up and running (such as php artisan migrate --force)" — with no slot specified. Forge's one concrete rule about ordering is about processes, not schemas: "you should place the restart command after the $ACTIVATE_RELEASE() macro to ensure the new code is activated before the process is restarted." That is step 7 above.
Finally, Laravel's own deployment documentation does not mention migrations at all.laravel.com/docs/13.x/deployment covers server requirements, nginx, optimize, reload, debug mode and the /up health route, and contains no occurrence of migrate, artisan down, or "maintenance mode". The framework delegates the entire question to the platforms. That is worth stating plainly: there is no canonical Laravel answer here to defer to.
2. Migrate before the flip — and the reason is Deployer, not Vapor
The most useful evidence is Deployer's Laravel recipe, because Deployer deploys to a box you own with an atomic symlink, which is precisely our shape. Its deploy task, verbatim from recipe/laravel.php:
php
task('deploy', [
'deploy:prepare',
'deploy:vendors',
'artisan:storage:link',
'artisan:optimize',
'artisan:migrate',
'deploy:publish',
'artisan:reload',
]);artisan:migrate is not commented out and not opt-in — task('artisan:migrate', artisan('migrate --force', ['skipIfNoEnv']));, where skipIfNoEnv only skips when there is no .env at all. And deploy:publish, from recipe/common.php, is where the flip lives:
php
task('deploy:publish', [
'deploy:symlink',
'deploy:unlock',
'deploy:cleanup',
'deploy:success',
]);So Deployer migrates from the new release directory while current still points at the old release, and only then moves the symlink. That is the ordering recommended above, arrived at independently by the tool with the most direct claim to our situation, and it agrees with Vapor's and Cloud's "before it goes live".
The reason is worth spelling out, because it is not obvious. Both orderings leave a window where code and schema disagree; they differ in which disagreement you get and in what a failure costs.
- Migrate before the flip. During the migration, and until the flip, the old code runs against the new schema. If the migration fails, nothing flipped: the previous release is still live and the deploy is a no-op from a visitor's point of view. The failure is recoverable by doing nothing.
- Migrate after the flip. Between the flip and the end of the migration, the new code runs against the old schema — a guaranteed
SQLSTATE[42S22]on any column the release introduced. And if the migration then fails, you are live on code that cannot work, and the only way out is a second symlink flip you now have to perform under pressure.
The first window is survivable only if the old code tolerates the new schema. The second window is never survivable. That asymmetry is the whole argument, and it is also why §3 is not optional decoration — the ordering is only safe because additive migrations make the first window benign.
For this repo the window is not theoretical. routes/console.php registers Schedule::command(PublishScheduledContent::class)->everyMinute(), so on a box with a schedule:run crontab line there is old application code executing during essentially any migration window that lasts more than a few seconds, plus a queue:work unit holding old code in memory until it is restarted. "Nobody is using the site at 2am" is not a defence when the site is calling itself.
3. Expand/contract, and whether a solo developer owes it anything
The pattern is Martin Fowler's ParallelChange:
Parallel change, also known as expand and contract, is a pattern to implement backward-incompatible changes to an interface in a safe manner, by breaking the change into three distinct phases: expand, migrate, and contract.
Its payoff, in Fowler's words, is exactly the property we need: "it allows your code to be released in any of these three phases." A schema is an interface between two releases of the application, and during a deploy both releases are, briefly, clients of it.
GitLab's migration documentation is the most detailed first-party statement of the practice I found, and it is candid about why the split exists:
The reason we spread this out across three releases is that dropping a column is a destructive operation that can't be rolled back easily. Following this procedure helps us to make sure there are no deployments to GitLab.com and upgrade processes for GitLab Self-Managed instances that lump together any of these steps.
They also name the exact hazard from §2: "During a zero-downtime deployment, a post-deployment migration runs while older processes still serve traffic."
Is the discipline worth it here? I have to be plain: no authoritative source addresses whether expand/contract earns its keep on a small or single-developer project. Fowler, GitLab, and the Flyway and Liquibase documentation all argue it from the premise of many clients, long transition periods, or self-managed customers on unknown versions — none of which apply. Everything I found arguing the small-team case is personal blog opinion. So what follows is judgement, labelled as such.
The judgement is that the discipline is not worth adopting, but the rule is, because for this repo they are not the same thing. GitLab's version is a three-release choreography with ignore-lists and post-deployment migration queues; that is fog at this scale. The rule underneath it is one sentence — a tagged release's migrations must not break the release before it — and honouring it costs almost nothing here, because the repo very nearly works this way already. Of the 35 files in database/migrations, 34 only create tables or add nullable columns: 2026_09_06_150002_add_price_checked_at_to_affiliate_links_table.php adds one nullable, indexed column and nothing else, and that is the house style.
The exception is instructive, and it is the reason to write the rule down rather than assume it. 2026_09_05_154430_add_pricing_and_merchant_to_affiliate_links_table.php does all three phases of parallel change inside a single migration file: it adds merchant_id and the pricing columns, backfills merchant_id from the free-text network values, and then drops network. Run that during step 4 against a live site and the previous release — which still selects network — breaks the instant the drop commits, and stays broken through a rollback. It ran in development, before anything was deployed, so it cost nothing; as a template for the next one it is exactly wrong.
What the rule changes, then, is only that a migration of that shape has to be split across two tags: v1.4.0 adds the column, backfills it and stops reading the old one; v1.5.0 drops the old one. One extra tag, on the rare release that needs one.
And that rule is what buys the thing the map already promised. "Rollback is a symlink flip" is only true if the old code survives the new schema. Expand/contract is not an alternative safety net to the dump — it is the mechanism that makes the advertised rollback work at all.
4. migrate:rollback is not used, and should not be wired into anything
Every primary source found converges. Nothing disagreed.
No first-party Laravel deploy tool offers a database rollback step. Deployer's rollback task, from recipe/deploy/rollback.php, re-symlinks current_path to a previous release and writes a BAD_RELEASE marker file; it issues no SQL and calls no artisan command. Its documentation contains no warning about migrations either — the topic is simply absent. Deployer does ship an artisan:migrate:rollback task, but it is not in the deploy list and nothing invokes it. Forge's rollback for standard deployments is git reset --hard and says nothing about the database; Vapor's rollback restores environment variables and secrets as they were at the time of the deployment being rolled back to, and documents no migration reversal.
The people who invented the practice deprioritised reverse scripts. Fowler and Sadalage, Evolutionary Database Design:
As well as automating the forward changes, you can consider automating reverse changes for each refactoring... We haven't found this to be cost effective and beneficial enough to try all the time, also we've not had much demand for it.
The dedicated migration tools say roll forward. Redgate's Flyway documentation, on implementing a rollback strategy:
As a general rule, when reverting database schema changes made to any live production database, it is not only simpler to roll forward, it also maintains the deployment audit trail which is all important for compliance purposes.
and, on the same page, "Rollback scripts (aka undo scripts) are no substitute for having a robust backup/restore strategy". Flyway's own undo migrations are a paid Teams-tier feature, which is its own comment on how central they are. Liquibase's rollback docs open with "Using the rollback command comes with risks to your database".
GitLab states the policy outright, in its migration style guide:
On GitLab production environments, if a problem occurs, a roll-forward strategy is used instead of rolling back migrations using
db:rollback.The
downmethod is used primarily in the development environment, for example, when a developer wants to ensure their local copy ofstructure.sqlfile and database are in a consistent state when switching between commits or branches.
That is the right way to read the 33 down() methods in database/migrations: they are a development convenience for branch-switching, and they should stay — but nothing on the deploy path should ever call them. Laravel's own migration documentation, for what it is worth, describes migrate:rollback --step and --batch neutrally and attaches no production-specific warning to them beyond the generic --force note; the framework neither endorses nor discourages the practice.
5. The failure mode where the migration succeeds and the deploy then fails
Steps 4 through 7 are not one transaction, and cannot be. Three sub-cases, in increasing nastiness.
The migration fails between files. Files 1–3 applied and are recorded in the migrations table; file 4 threw. current never moved, so the site is fine. Re-running migrate --force after fixing file 4 resumes from file 4. This is the good case, and it is the case the migrate-before-flip ordering is designed to produce.
The migration fails within a file, on MySQL. This is the one worth understanding, and it is specific to MySQL. Laravel wraps a migration in a transaction only when the schema grammar says it can — from Migrator::runMigration:
php
$this->getSchemaGrammar($connection)->supportsSchemaTransactions()
&& $migration->withinTransaction
? $connection->transaction($callback)
: $callback();The base schema Grammar declares protected $transactions = false;. PostgresGrammar overrides it to true. MySqlGrammar does not mention transactions at all, so it inherits false — every migration against MySQL runs unwrapped, statement by statement. That is not a Laravel shortcoming; it is MySQL's, and the manual is unambiguous about why. From Atomic DDL:
Atomic DDL is not transactional DDL. DDL statements, atomic or otherwise, implicitly end any transaction that is active in the current session, as if you had done a
COMMITbefore executing the statement. This means that DDL statements cannot be performed within another transaction, within transaction control statements such asSTART TRANSACTION ... COMMIT, or combined with other statements within the same transaction.
MySQL 8 guarantees that a single ALTER TABLE either happens or does not. It guarantees nothing about three of them in one migration file. And Laravel records a migration as run only after it completes — in Migrator::runUp, $this->repository->log($name, $batch) comes after the call that executes it. So a migration file that adds two columns and fails on the second leaves column one in place and the file absent from the migrations table; the next migrate --force re-runs it from the top and fails immediately on a duplicate column.
The repo already contains the shape that triggers this. 2026_09_05_154430_add_pricing_and_merchant_to_affiliate_links_table.php issues DDL, then a data backfill, then more DDL, in one up(). On MySQL each of those commits independently and the file is recorded only if all of them finish; a failure in the backfill leaves the new columns in place, the old one still present, the data half-migrated and the file unrecorded.
There is no automated way out of that, and pretending otherwise is where deploy scripts start lying. The honest mitigations are three: one schema change per migration file, so the atomic unit MySQL does guarantee lines up with the unit Laravel records; migrate --pretend in step 2 so the operator can see exactly which statements were in flight; and the dump from step 3 as the floor.
The migration succeeds and a later step fails. Step 6 or 7 blows up — the symlink flip fails, the queue unit will not start, the smoke test returns 500. The schema is new; the code live is old. This is exactly the state expand/contract is for, and if the release's migrations were additive, the site keeps working and you fix forward at your leisure. If they were not, the site is down and no symlink can help. The severity of this failure is a function of a decision made when the migration was written, not of anything the deploy script does.
One more case belongs here, from GitHub's workflow-cancellation reference: a cancelled job gets SIGINT, then SIGTERM 7500 ms later, and "If the process is still running, the runner kills the process tree", with the server force-terminating everything after five minutes. So hitting cancel in the Actions UI during step 4 produces the half-applied state above. The operational rule is short: once the migrate step has started, let it finish.
6. Dump before migrate — worth doing, but be clear what it is
It is not standard. None of Envoyer, Forge, Vapor or Cloud takes a pre-migration dump; not one of their deployment pages mentions backups. That is not an argument against doing it — the managed platforms sit on managed databases with their own snapshots, and our box will not — but the claim "everyone dumps before migrating" is not supportable, and the ticket should not rest on it.
The cost is not documented. The MySQL manual gives no guidance on dump duration or size thresholds, and I am not going to invent a number. What can be said from the documentation is the shape: mysqldump is a logical dump, so its cost scales with row count, and this database's large tables will be clicks, activity_log, sessions and cache rather than content. Measure it on the box once MySQL exists (issue 15) and put the real number in the runbook; if it ever stops being seconds, that is the signal to move to a scheduled snapshot rather than a per-deploy one.
The invocation, with every flag justified from the mysqldump manual:
sh
mysqldump --single-transaction --quick --routines --triggers --events \
--no-tablespaces --default-character-set=utf8mb4 \
"$DB_DATABASE" | gzip > "/var/backups/reviewly/pre-deploy-${TAG}-$(date -u +%Y%m%dT%H%M%SZ).sql.gz"--single-transaction— "It is useful only with transactional tables such as InnoDB, because then it dumps the consistent state of the database at the time when BEGIN was issued without blocking any applications." Everything here is InnoDB, so we get a consistent snapshot with no read lock on a live site.- The caveat that decides the ordering of steps 3 and 4: "While a
--single-transactiondump is in process, to ensure a valid dump file (correct table contents and binary log coordinates), no other connection should use the following statements:ALTER TABLE,CREATE TABLE,DROP TABLE,RENAME TABLE,TRUNCATE TABLE. A consistent read is not isolated from those statements." This is why the dump must complete beforemigratestarts, not run alongside it — a dump racing its own migration is worthless in the one situation you would want it. --quick— "Retrieve rows for a table from the server a row at a time"; the manual pairs it with--single-transactionfor large tables.--routines,--triggers,--events— none of these exist in the schema today, but a dump that silently omits a category of object is a dump you cannot trust later.--no-tablespaces— the manual's privilege list requiresPROCESS"if the--no-tablespacesoption is not used". Passing it keeps the deploy user's grants toSELECT,SHOW VIEW,TRIGGERand DDL on its own schema, instead of a server-wide privilege. This is the flag whose absence produces the well-known "Access denied; you need (at least one of) the PROCESS privilege(s)" failure on MySQL 8.
A sourcing note: dev.mysql.com truncated or bot-blocked several direct fetches of the mysqldump page during this research. The --single-transaction and privilege quotes above were corroborated against the man7 mirror of the same upstream manual text; the --no-tablespaces description and the PROCESS requirement were read directly from dev.mysql.com. Treat the DDL-warning wording as verified-by-mirror rather than verified-in-place.
The restore procedure, from Reloading SQL-Format Backups, is mysql db_name < dump.sql — for a single-database dump taken without --databases, the file carries no CREATE DATABASE or USE, so the target database must exist and be named on the command line. In practice, for us:
sh
php artisan down # from the live release
sudo systemctl stop reviewly-queue # stop writers, including the scheduler's children
gunzip -c /var/backups/reviewly/pre-deploy-vX.Y.Z-....sql.gz | mysql "$DB_DATABASE"
# flip `current` back to the previous release
php artisan upThat sequence has never been run on this box. An untested restore is a belief, not a backup, and the map already lists "whether a restore has ever been tested" as unspecified. It should be tested once against a scratch database before anyone relies on the paragraph above.
And a repo-specific reason to distrust the restore. SESSION_DRIVER, QUEUE_CONNECTION and CACHE_STORE are all database in this application. Restoring a dump therefore also restores the sessions, jobs, job_batches, failed_jobs, cache and cache_locks tables to their state at dump time — which means re-queueing jobs that have already run, resurrecting withoutOverlapping locks (RefreshMerchantPrices uses one) that may then block the scheduler until they expire, and rewinding every logged-in admin's session. A restore is not a neutral rewind. If one is ever performed, those six tables should be truncated afterwards rather than trusted.
7. Things specific to a self-hosted runner on the same box
The runner is the deploy user, and it needs the database. Because the runner executes on the target box, migrate --force runs as whatever account the runner service runs as, reading a decrypted .env. That collides with a constraint already settled in the map: the LARAVEL_ENV_ENCRYPTION_KEY "lives in a root-only file on the box". If the key file is root-only and the runner is not root, the deploy cannot decrypt the environment it needs to migrate. Something has to give — a group-readable key file owned by the deploy user, or a narrowly-scoped sudo rule for the decrypt step. This is issue 21's decision, but the migration step is the thing that forces it, so it should be raised there.
GitHub's security hardening guidance is blunt about the exposure: "Self-hosted runners should almost never be used for public repositories on GitHub, because any user can open pull requests against the repository and compromise the environment", and "any user capable of invoking workflows has access to this environment." The map already handles the first half by keeping PR CI on GitHub-hosted runners. The second half is the reason the deploy job should be attached to a GitHub Environment: the docs note that "A job that references an environment must follow any protection rules for the environment before running or accessing the environment's secrets", and environments support required reviewers and a wait timer. For a solo developer a required reviewer is theatre, but the wait timer is not — a short delay is a free undo on a mistyped tag, before anything has touched the schema. (I could not find GitHub documentation stating what OS account the runner service itself should run as; that guidance exists only in third-party hardening write-ups, so treat it as unsourced.)
Use Actions concurrency, not migrate --isolated. Laravel offers --isolated for exactly the "two servers migrating at once" problem, and it would technically work here — it requires a shared cache driver, and database is on its supported list. Do not use it. From the migrations docs:
All other attempts to run the
migratecommand while that lock is held will not execute; however, the command will still exit with a successful exit status code.
A deploy whose migrate step silently exits 0 without migrating, and then flips the symlink onto new code and an old schema, is the §2 disaster case reached by a route that looks like success in the logs. The correct tool is the workflow's own concurrency block, where "only a single job or workflow using the same concurrency group will run at a time" and a second run queues instead of proceeding. Leave cancel-in-progress at its default of false — the docs are clear that setting it true would "also cancel any currently running job or workflow in the same concurrency group", which is precisely the mid-migration kill from §5.
Everything is one blast radius. There is no network boundary between the thing running the migration and the thing serving the site, and no staging copy to fail on first. The compensating controls are the ones already listed: PR CI on GitHub-hosted runners so untrusted code never gets here, --pretend output in the log, the dump, and the ordering that leaves the site untouched when a migration fails.
What rollback will and will not recover
Stated as plainly as the ticket asks for it.
A symlink flip back recovers, completely and instantly: the application code, the compiled assets in public/build, the cached config, routes, events and views, and the vendor tree. That is the entire content of a release directory, and it is genuinely atomic.
A symlink flip back recovers nothing about the database. The migration that ran is still applied and still listed in the migrations table. If it was additive, the old code will not notice and the rollback is a real rollback. If it dropped, renamed, narrowed or added-NOT-NULL to anything the old code touches, the old code will fatal, and you have rolled back into a second outage. This is the single reason §3's rule exists, and it is the difference between the map's "rollback is a symlink flip" being true and being a slogan.
migrate:rollback is not a recovery tool and is not part of this plan. Its down() methods are written for local branch-switching, they have never been executed against production data, and on MySQL they are not transactional either — a failing down() leaves the same half-applied state as a failing up(), on top of whatever was already wrong. Two of the 35 migrations (create_activity_log_table, create_media_table, both vendor-published) have no down() at all.
Restoring the dump recovers the schema and loses time. Everything written between the dump and the restore is gone: clicks recorded against affiliate links — which is revenue attribution, not telemetry — activity_log entries, any content an editor saved, and every price and price_checked_at the hourly RefreshMerchantPrices run wrote. It also rewinds sessions, cached values, locks and the job queue, as §6 describes.
Nothing recovers files on disk. Media Library uploads live under the shared storage/ path, not in the database and not in the release directory. A dump restore un-writes the rows that point at them while leaving the files; anything uploaded after the dump becomes an orphaned file with no row. The two stores cannot be rolled back together, and no amount of deploy tooling changes that.
What that adds up to. The dump is the floor, not the plan. Realistically it will never be restored, because by the time restoring it looks attractive the data loss will cost more than the schema problem. It is worth keeping anyway — it is seconds and a few megabytes, and the one scenario it covers, a migration that destroys data that cannot be recomputed, is unbounded without it. But the thing actually protecting this site is the ordering in §2 and the rule in §3: migrate before you flip, so a bad migration costs a deploy instead of an outage, and keep migrations additive within a release, so the flip back is real.
Sources
- Laravel 13 — Migrations, Deployment
- Laravel framework source — Migrator, schema Grammar, MySqlGrammar
- Envoyer — Deployment Hooks
- Forge — Deployments, Forge deployment rollbacks
- Vapor — Deployments
- Laravel Cloud — Environments
- Deployer — recipe/laravel.php, recipe/common.php, recipe/deploy/rollback.php
- Martin Fowler — ParallelChange, Evolutionary Database Design
- GitLab — Avoiding downtime in migrations, Migration style guide
- Redgate Flyway — Implementing a roll back strategy, Undo migrations
- Liquibase — rollback
- MySQL 8.4 — Atomic DDL, mysqldump (man7 mirror), Reloading SQL-Format Backups
- GitHub Actions — Security hardening, Workflow cancellation,
concurrency, Using environments for deployment
Claims I could not verify
- Whether a failing deploy command aborts activation on Laravel Cloud. The timing is documented; the failure semantics are not. Vapor documents both.
- Where Envoyer and Forge intend a migration hook to sit relative to release activation. Neither documents a recommendation; §2's ordering comes from Deployer, Vapor and Cloud.
- Whether expand/contract is worth the overhead on a small or solo project. No authoritative source addresses it; §3's answer is labelled judgement.
- What OS account a GitHub Actions self-hosted runner service should run as. Not in GitHub's docs.
mysqldumpduration and size expectations. The MySQL manual gives none, and none are invented here — measure on the box.