Laravel migrations as a release step

On a classic server, deploying Laravel often means SSH, git pull, php artisan migrate --force and hoping nothing breaks in between. On Brewless, migrations are a step of the release itself, with a clear rule: the new code only goes live when its migrations succeeded.

That rule gives you a safety net, and it puts one demand on how you write migrations. This tutorial covers both.

When do Laravel migrations run on Brewless?#

On every deploy, after the image is built and before the new release goes live. Brewless runs the release commands, migrate --force by default, on a container with the new image. If they succeed, the web container switches to the new image; if one fails, nothing changes for visitors.

Where the step sits in a deploy#

A deploy runs through these steps, and the console and brewless deploy show each one:

1. Pack the current commit.
2. Upload it into a private bucket of your own Scaleway project.
3. Build the image, in a job in your project.
4. Migrate: run the release commands on the new image.
5. Go live: switch the web container to the new image, check its health route, then move the workers.

The release commands run on the release container, a third container of the environment next to web and worker. Brewless calls a route of the brewless/laravel package on it with a secret of its own, and the package runs the commands in your application, with its own database connection. You never run migrations by hand in a container, and the start script should not run them either: it runs on every cold start of every container.

A failing migration keeps the old release live#

When a release command fails, the release gets the status Failed and never goes live. The web container still runs the previous image, and visitors notice nothing.

brewless deploy production

The client says the release commands failed and that the previous release keeps serving. Why they failed is in your application's own log, not at Brewless, because an error can quote the data it failed on:

brewless logs production --source=release

Fix the migration, commit, and deploy again.

Warning

A failed release can still have changed the database. Migrations that ran before the one that failed stay applied. On PostgreSQL, Laravel runs each migration in a transaction, so the one that failed leaves nothing half done; on MySQL a schema change cannot be rolled back, and a migration can stop halfway. Check with brewless command production "migrate:status".

90 seconds per release#

The release commands get 90 seconds per release, all of them together. That holds whatever timeout you give the release container in brewless.yml.

Ninety seconds is plenty for schema changes: adding a table, a column or an index on a table of normal size. It is not enough for rewriting millions of rows. Keep the two apart:

• Schema changes go in migrations.
• Data changes on large tables go in a queued job or a command, dispatched or run once the release is live.

brewless command production "orders:backfill-totals"

A one-off command gets 50 seconds. Work that takes longer belongs in a queued job, which gets the worker's timeout instead.

The window between migrate and go live#

This is the part that shapes how you write migrations. The steps above mean that for a moment, and sometimes longer, the database already has the new schema while the old code still serves visitors:

Three cases put old code on the new schema:

1. During the deploy. Between the migrate step and the switch, the old release keeps serving.
2. When going live fails. The migrations succeeded, but the new container does not start or does not answer healthy. The previous release keeps serving, now on the new schema.
3. After a rollback. A rollback puts the image of an earlier release live again, and runs its release commands, but nothing is migrated back. The console tells you before you confirm when later releases changed the database.

So the rule for every migration: the code that is live before it must keep working after it.

Expand, then contract#

The way to follow that rule is to split a breaking change over two or more deploys. First you expand the schema so old and new code both work, then, once nothing uses the old shape any more, you contract it.

Renaming users.name to users.full_name in one migration breaks the old code the moment the migration ran. Split it:

Deploy 1: expand. Add the new column, and have the new code write both.

return new class extends Migration
{
    public function up(): void
    {
        Schema::table('users', function (Blueprint $table): void {
            $table->string('full_name')->nullable();
        });
    }

    public function down(): void
    {
        Schema::table('users', function (Blueprint $table): void {
            $table->dropColumn('full_name');
        });
    }
};

Between the deploys: backfill. Copy name into full_name for existing rows, in a queued job or a command, so it is not bound to the 90 seconds.

Deploy 2: switch reads. The code reads full_name only. The old column is still there, so a rollback to deploy 1 still works.

Deploy 3: contract. Drop name. By now no release you would roll back to reads it.

The same pattern covers most changes:

Tip

Dropping a column the model still lists in $fillable or $casts, or that a query selects by name, breaks the old code. Remove those references in one deploy and the column in the next.

Choosing the release commands#

By default the release commands are migrate --force. A release list in brewless.yml replaces them, and runs in the order you give:

organisation: acme
application: shop
framework: laravel
release:
  - migrate --force
  - cache:clear

A few rules apply:

• The list needs brewless/laravel 0.3 or later. With an older version the application runs its own commands, and the release does not go live, with a message that says so.
• Commands run on every deploy, and again on a rollback, so each one has to be safe to run twice. migrate --force is: it only runs what has not run yet.
• Commands that never end, such as queue:work, schedule:work or tinker, are refused.
• Commands that throw data away are refused: db:wipe, migrate:fresh, migrate:refresh, migrate:reset and migrate:rollback. That is a step someone takes on purpose, not a side effect of a deploy.

The list goes along with each release, so a rollback runs the commands that release was deployed with.

Summary#

1. Migrations run before the release goes live; a failure keeps the old release serving.
2. All release commands together get 90 seconds. Move large data changes into jobs.
3. The old code runs on the new schema during a deploy, after a failed switch and after a rollback. Write every migration so the live code keeps working.
4. Split breaking changes: expand, backfill, switch, contract.
5. Set your own release list when you need more than migrate --force.

The steps of a deploy are in Deployments, and what a rollback does and does not undo is in Rollbacks.