Should you publish package migrations?

It is common for a Laravel package to also provide migrations, adding necessary tables or columns to your database.

Let's consider Cashier as a concrete example. It provides migrations that add columns to your users table, and adds a new subscriptions table.

The Cashier installation docs tell you that you should publish these migrations into your project, but if you don't, they will still run. (At least they did until Laravel 11, where this behavior changed with first-party packages.)

Other packages leave it up to you and don't make a recommendation. So what should you do?

I recommend always publishing the migrations. Here are a few reasons why:

1. You can see what's going on. By publishing the migration, it's easier for you to review, and visible in the PR review as well.
2. It's predictable. When you later upgrade that package, no more guessing if a migration changed out from under you.
3. Now you can customize it, if necessary. If you need to tweak the migration, you can do so without modifying the package itself.
4. The sequencing is more predictable. When you publish a migration, it gets the current timestamp. Running it from the package will use the original timestamp.

It might seem more convenient to just run the migrations from inside the package, but it can lead to unpleasant surprises.

Here to help,

Joel

P.S. Do you have people to fall back on if you get stuck or can’t seem to solve a problem in your code? If not, then what you need is the Mastering Laravel community. See you inside!